Merge pull request 'build(git-sync): пакет @docmost/git-sync в develop, code-only (#326 step 1 / PR-A)' (#327) from feat/293-A-git-sync-package into develop

Reviewed-on: #327

.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
+# cannot poison a reused socket into a PRE-RESPONSE `read ECONNRESET`. Kept under
-# your egress drops idle connections faster than ~10s. Default 10000 (10 s).
+# common ~5s upstream/middlebox idle cutoffs so undici recycles the socket before
-# AI_STREAM_KEEPALIVE_MS=10000
+# 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,
+    "version": 5,
-    "hash": "a94931fbd20272570a588c72159ac9e48a89c99bd8f718449cda5e7ca4280fdf"
+    "hash": "d7769872968109a1ccfb58d71bc3f3564a750b91766156f59031762848de4f24"
   },
   "line-editor": {
-    "version": 2,
+    "version": 4,
-    "hash": "cca324110dc6f96d2a8a239a2fb95b0ba09fad5806c9b6090a3c210ea7883ceb"
+    "hash": "890d10f3f0bd7f2b2cfcc94463634221c557a3140e3794721748dc8d99979780"
   },
   "narrator": {
-    "version": 1,
+    "version": 2,
-    "hash": "36b38785fea6ae1c70bf6fb6b29ae5278bb86e389e61f7b9736675a589fa434c"
+    "hash": "66fe653003b4f63ef3c3a5c5c48552fe47daeefffc16907c37c35f0e8da98851"
   },
   "proofreader": {
-    "version": 3,
+    "version": 7,
-    "hash": "a36047c5cab837b2a727f63d4ddafc269b1fc44b90b365e770ecdb8f77e13952"
+    "hash": "fdf8e0a443fa3c4102095e024146401363629a3f9015fb938c7bac2642825e56"
   },
   "researcher": {
     "version": 1,
     "hash": "853658fda43ddbe0a4d08f2c6e50b5116d29a2e9ccd7f46e173e65920d8f6ace"
   },
   "structural-editor": {
-    "version": 2,
+    "version": 4,
-    "hash": "83093baa7262aef8193871a1afcf2b43b11a56fe2d00cade41355cf66d972b74"
+    "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

@@ -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",
@@ -1229,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

@@ -3,6 +3,7 @@ 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,
@@ -13,6 +14,18 @@ import {
 
 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");
@@ -27,7 +40,7 @@ function renderStack(props: Props) {
 }
 
 describe("AgentAvatarStack", () => {
-  it("internal chat WITH role: emoji glyph in front + human launcher behind", () => {
+  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 },
@@ -43,6 +56,57 @@ describe("AgentAvatarStack", () => {
     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 },
@@ -74,7 +138,7 @@ describe("AgentAvatarStack", () => {
     expect(screen.getByText("Bob")).toBeDefined();
   });
 
-  it("external MCP: agent avatar in front, NO launcher behind", () => {
+  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,

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

@@ -1,9 +1,10 @@
-import { Avatar, Box, Group, Text, Tooltip } from "@mantine/core";
+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,
@@ -23,19 +24,17 @@ export interface LauncherInfo {
   avatarUrl?: string | null;
 }
 
-// Same violet token as the former AiAgentBadge (which used color="violet").
-const AGENT_COLOR = "violet";
 const GLYPH_SIZE = 38;
 const LAUNCHER_SIZE = 22;
-// How far the launcher avatar sticks out past the agent's bottom-right corner, so
+// How far the launcher avatar sticks out past the agent's top-right corner — it
-// the "human behind" reads as behind (lower z-index) yet stays clearly visible.
+// 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 violet circle.
+ *   2. agent.emoji     -> the role emoji on a per-agent gradient circle.
- *   3. otherwise       -> the IconSparkles glyph on a violet circle (fallback).
+ *   3. otherwise       -> the IconSparkles glyph on a per-agent gradient circle.
  */
 function AgentGlyph({ agent }: { agent: AgentInfo }) {
   if (agent.avatarUrl) {
@@ -48,20 +47,42 @@ function AgentGlyph({ agent }: { agent: AgentInfo }) {
     );
   }
 
-  if (agent.emoji) {
+  // Emoji/sparkles glyph on a per-agent gradient circle (color, gradient partner
-    return (
+  // and split angle all hashed from the agent name via avatarStyle — see
-      <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
+  // @/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>
-      </Avatar>
+      ) : (
-    );
+        <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
-  }
+      )}
-
+    </Box>
-  return (
-    <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
-      <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
-    </Avatar>
   );
 }
 
@@ -81,8 +102,10 @@ export interface AgentAvatarStackProps {
 }
 
 /**
- * The "agent avatar stack" (#300): the AGENT glyph in front, and — for an
+ * The "agent avatar stack" (#300): the AGENT glyph, and — for an internal AI
- * internal AI chat — the HUMAN who launched it as a smaller avatar offset behind.
+ * 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
@@ -156,7 +179,9 @@ export function AgentAvatarStack({
         : {})}
     >
       {launcher && (
-        <Box pos="absolute" bottom={0} right={0} style={{ zIndex: 0 }}>
+        // 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}
@@ -165,8 +190,8 @@ export function AgentAvatarStack({
           />
         </Box>
       )}
-      {/* Pin the agent glyph to the top-left at its own size; the launcher then
+      {/* The agent glyph keeps its own size (flex-centered in the container); the
-          overhangs it by LAUNCHER_OVERHANG at the bottom-right and stays visible. */}
+          launcher overhangs it by LAUNCHER_OVERHANG at the top-right and stays visible. */}
       <Box
         style={{
           position: "relative",

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
+       margins. The streaming plain-text path that needs pre-wrap sets it
-       inline itself (see reasoning-block.tsx). */
+       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 =>
+// Pass an explicit `id` when a test renders several rows at once.
-  ({ id: "m1", role: "assistant", parts }) as UIMessage;
+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
+  // Markdown parse invariant (per throttled ~20Hz stream delta the text GROWS):
-  // by an unrelated streamed delta) does not re-parse the reasoning text; it
+  //  1. Collapsed -> never parse (#302): the html is only shown inside
-  // recomputes only when the reasoning text itself changes (while it streams in).
+  //     <Collapse in={open}>, so parsing for a hidden body would be an O(n²)
-  // collapseBlankLines collapses the blank-line gaps the model emits between every
+  //     marked + DOMPurify storm.
-  // list item / paragraph so the reasoning renders compactly (tight lists, joined
+  //  2. Expanded + STREAMING -> no parse and no innerHTML swaps either: the body
-  // paragraphs) — ONLY here, not in the normal answer.
+  //     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
+            // Still streaming (or markdown yielded nothing): chunked plain text.
-              className={classes.reasoningText}
+            // The wrapper carries the reasoningText styling; each chunk sets its
-              style={{ whiteSpace: "pre-wrap" }}
+            // own pre-wrap inline (NOT on this div — see ai-chat.module.css).
-            >
+            <div className={classes.reasoningText}>
-              {trimmed}
+              <StreamingPlainText text={trimmed} />
-            </Text>
+            </div>
           )}
         </Collapse>
       )}
@@ -92,7 +105,7 @@ function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
   );
 }
 
-// Memoized: re-renders only when `text`/`tokens` change (primitive props, default
+// Memoized: re-renders only when `text`/`tokens`/`streaming` change (primitive
-// shallow compare), so a parent re-render during streaming of OTHER content does
+// props, default shallow compare), so a parent re-render during streaming of OTHER
-// not re-run the markdown parse for an already-finalized reasoning block.
+// 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,10 +38,15 @@ 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>,
   );
 }
@@ -87,3 +98,87 @@ describe("CommentListItem — agent avatar stack", () => {
   // 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,4 +1,4 @@
-import { Group, Text, Box } from "@mantine/core";
+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";
@@ -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}"]`,
@@ -211,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

@@ -28,6 +28,13 @@ 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).

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.
+    // a confusing second click can't fire while the model loads. The error case
-    const label = status === "loading" ? t("Preparing…") : t("Transcribing…");
+    // 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>
+    <Tooltip
-      <ActionIcon
+      label={reasonLabel ?? t("Start dictation")}
-        size={size}
+      withArrow
-        variant="subtle"
+    >
-        color={color}
+      {icon}
-        onClick={() => void start()}
-        disabled={disabled}
-        aria-label={t("Start dictation")}
-      >
-        <IconMicrophone size={resolvedIconSize} />
-      </ActionIcon>
     </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({
+      const message = dictationErrorMessage("no-media-devices", t);
-        color: "red",
+      notifications.show({ color: "red", message });
-        message: t("Audio recording is not available in this browser/context"),
+      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);
+      const rawDetail = (err as { message?: string })?.message ?? String(err);
-      let message: string;
+      // Prefix the DOMException name (e.g. "TypeError: …") so the generic
-      if (name === "NotAllowedError" || name === "SecurityError") {
+      // resolver branch reproduces this hook's original "Could not start
-        message = t("Microphone access denied");
+      // recording: <name>: <detail>" text. Each caller owns its own detail; the
-      } else if (name === "NotFoundError" || name === "OverconstrainedError") {
+      // streaming hook intentionally does not add the name.
-        message = t("No microphone found");
+      const detail = `${name ? `${name}: ` : ""}${rawDetail}`;
-      } else if (name === "NotReadableError" || name === "AbortError") {
+      const code = classifyGetUserMediaError(err);
-        message = t("Microphone is unavailable or already in use");
+      const message = dictationErrorMessage(code, t, { detail });
-      } else {
-        // Unknown failure: show the real reason instead of a generic string.
-        message = `${t("Could not start recording")}: ${name ? `${name}: ` : ""}${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({
+      const detail = (err as { message?: string })?.message ?? String(err);
-        color: "red",
+      const message = dictationErrorMessage("recorder-failed", t, { detail });
-        message: `${t("Could not start recording")}: ${(err as { message?: string })?.message ?? String(err)}`,
+      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 = (
+          const { code, serverMessage } = classifyTranscriptionError(err);
-            err as { response?: { status?: number; data?: { message?: string } } }
+          const detail = (err as { message?: string })?.message ?? String(err);
-          )?.response;
+          const message = dictationErrorMessage(code, t, {
-          const serverMsg = resp?.data?.message;
+            serverMessage,
-          let message: string;
+            detail,
-          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)}`;
-          }
           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({
+      const detail = (err as { message?: string })?.message ?? String(err);
-        color: "red",
+      const message = dictationErrorMessage("recorder-failed", t, { detail });
-        message: `${t("Could not start recording")}: ${(err as { message?: string })?.message ?? String(err)}`,
+      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({
+          const { code, serverMessage } = classifyTranscriptionError(err);
-            color: "red",
+          const detail = (err as { message?: string })?.message ?? String(err);
-            message: transcriptionErrorMessage(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({
+      const message = dictationErrorMessage("vad-init-failed", t, { detail });
-        color: "red",
+      notifications.show({ color: "red", message });
-        message: `${t("Could not start recording")}: ${detail}`,
+      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;
+      const code = classifyGetUserMediaError(err);
-      if (name === "NotAllowedError" || name === "SecurityError") {
+      const message = dictationErrorMessage(code, t, { detail });
-        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}`;
-      }
       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/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
+            {/* Desktop: full labeled buttons. */}
-              size="xs"
+            <Group gap="xs" wrap="nowrap" visibleFrom="sm">
-              variant="subtle"
+              <Button
-              color="red"
+                size="xs"
-              leftSection={<IconTrash size={16} />}
+                variant="subtle"
-              onClick={handleTrashNow}
+                color="red"
-              loading={isDeleting}
+                leftSection={<IconTrash size={16} />}
-            >
+                onClick={handleTrashNow}
-              {t("Move to trash")}
+                loading={isDeleting}
-            </Button>
+              >
-            <Button
+                {t("Move to trash")}
-              size="xs"
+              </Button>
-              variant="light"
+              <Button
-              color="orange"
+                size="xs"
-              leftSection={<IconClockHour4 size={16} />}
+                variant="light"
-              onClick={handleMakePermanent}
+                color="orange"
-              loading={toggleTemporary.isPending}
+                leftSection={<IconClockHour4 size={16} />}
-            >
+                onClick={handleMakePermanent}
-              {t("Make permanent")}
+                loading={toggleTemporary.isPending}
-            </Button>
+              >
-          </Group>
+                {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/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],
-  ) {
+  ): ReturnType<CollabEventHandlers[TName]> {
-    return this.redisSync?.handleEvent(eventName, documentName, payload);
+    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,
+    // `fn` MUST be synchronous: hocuspocus `connection.transact(fn)` runs fn
-  ): Promise<void> {
+    // 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
+ * Wiring spec for the #191 `POST /ai-chat/bound-chat` endpoint, hardened for
- * the requesting user + workspace + pageId to findLatestByPage and return the
+ * #312. `dto.pageId` carries either a page slugId (10-char nanoid, off a slug
- * matched chat's id, or `{ chatId: null }` when there is none. The repo already
+ * URL) or a page uuid, so the controller must FIRST resolve it to a real page
- * scopes to the caller's OWN chats, so a foreign pageId simply yields no match
+ * uuid via PageRepo.findById (which accepts both) — passing the raw slugId into
- * (null) — no extra page-access check is needed. Exercised with hand-rolled
+ * the uuid ai_chats.page_id column caused a Postgres 22P02 500. Only then is the
- * mocks, no Nest graph and no DB.
+ * 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 () => {
+  it('resolves a slugId to the page uuid and returns the owned chat id', async () => {
-    const { controller, aiChatRepo } = makeController({
+    const { controller, aiChatRepo, pageRepo } = makeController({
-      id: 'c1',
+      // findById accepts a slugId and returns the page with its real uuid.
-      creatorId: 'u1',
+      page: { id: 'page-uuid-1', workspaceId: 'ws1' },
+      chat: { id: 'c1', creatorId: 'u1' },
     });
-    const res = await controller.boundChat({ pageId: 'p1' }, user, workspace);
+    // The client sends a 10-char nanoid slugId, NOT a uuid.
-    expect(aiChatRepo.findLatestByPage).toHaveBeenCalledWith('u1', 'ws1', 'p1');
+    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 () => {
+  it('returns { chatId: null } for a page in a DIFFERENT workspace without a chat lookup', async () => {
-    const { controller } = makeController(undefined);
+    const { controller, aiChatRepo, pageRepo } = makeController({
-    const res = await controller.boundChat({ pageId: 'foreign' }, user, workspace);
+      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
+   * { chatId: null } when the page has no owned chat (-> a fresh chat).
-   * access check needed: only the caller's OWN chats are matched, so a foreign
+   *
-   * pageId reveals nothing.
+   * `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 ' +
+          'copied verbatim from a single paragraph/block. You may also attach a ' +
-          'comment UI.',
+          '`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 }) => {
+        execute: async ({
-          // createComment(pageId, content, type, selection?, parentCommentId?).
+          pageId,
-          // Top-level comments are inline and must carry a selection to anchor
+          content,
-          // on; replies inherit the parent's anchor (no selection). Throwing
+          selection,
-          // here surfaces a tool error to the model (Vercel `ai` SDK) so the
+          parentCommentId,
-          // agent retries with a better selection — do not catch/suppress it.
+          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({
+      // Schema + description from the shared registry (identical across both
-        description:
+      // transports). The execute body keeps its OWN parseNodeArg normalization:
-          'Replace a single content block (by id) with a new ProseMirror ' +
+      // the model sometimes serializes the node as a JSON string, and we parse it
-          'node; the replacement keeps the same nodeId. Example node: a ' +
+      // before the client's typeof-object guard rejects it (parity with the
-          'paragraph {"type":"paragraph","content":[{"type":"text","text":"Hello"}]} ' +
+      // standalone MCP server, index.ts patch_node).
-          'or a heading {"type":"heading","attrs":{"level":2},"content":' +
+      patchNode: sharedTool(
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+        sharedToolSpecs.patchNode,
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
+        async ({ pageId, nodeId, node }) => {
-          '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.
           const parsedNode = parseNodeArg(node);
           return await client.patchNode(pageId, nodeId, parsedNode);
         },
-      }),
+      ),
 
-      insertNode: tool({
+      // Shared registry schema + description; execute retains parseNodeArg on the
-        description:
+      // incoming node (parity with the standalone MCP server, index.ts
-          'Insert a ProseMirror node relative to an anchor, or append it at ' +
+      // insert_node).
-          'the top level. For before/after you MUST provide EXACTLY ONE of ' +
+      insertNode: sharedTool(
-          'anchorNodeId or anchorText. Example node: a paragraph ' +
+        sharedToolSpecs.insertNode,
-          '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+        async ({ pageId, node, position, anchorNodeId, anchorText }) => {
-          '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.
           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

@@ -61,6 +61,8 @@ describe('CommentService — broadcast carries the agent avatar stack', () => {
     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,
@@ -68,6 +70,7 @@ describe('CommentService — broadcast carries the agent avatar stack', () => {
       collaborationGateway,
       generalQueue,
       notificationQueue,
+      auditService,
     );
 
     return { service, commentRepo, wsService };

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'),
@@ -299,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/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,
+      keepAliveTimeout: 4_000,
-      keepAliveMaxTimeout: 10_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';
+    process.env.AI_STREAM_KEEPALIVE_MS = '7000';
-    expect(streamKeepAliveMs()).toBe(4000);
+    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.
+  // The budget is env-driven (AI_STREAM_PRE_RESPONSE_RETRIES, default 4 -> 5
-  const MAX_ATTEMPTS = 3;
+  // 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
+ * Default number of times to retry a PRE-RESPONSE connection failure (a
- * before ANY response byte) on a fresh connection. Safe because `fetch()` only
+ * reset/timeout before ANY response byte) on a fresh connection. Safe because
- * rejects before the Response resolves — a started stream is never replayed.
+ * `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 (
+        if (aborted || attempt >= maxRetries || !isRetryableConnectError(err)) {
-          aborted ||
-          attempt >= PRE_RESPONSE_CONNECT_RETRIES ||
-          !isRetryableConnectError(err)
-        ) {
           throw err;
         }
-        // Brief backoff before the fresh-connection retry.
+        // Jittered backoff before the fresh-connection retry (anti-thundering-herd).
-        await new Promise((resolve) => setTimeout(resolve, 150 * (attempt + 1)));
+        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>;

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

@@ -1,170 +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).
- */
-import { sanitizeTitle, disambiguate } from "./sanitize.js";
-/**
- * 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 function buildVaultLayout(pages) {
-    // Index pages by id so the parent chain can be walked. Guard against
-    // duplicate ids in the input (first one wins).
-    const byId = new Map();
-    for (const p of pages) {
-        if (p && p.id && !byId.has(p.id))
-            byId.set(p.id, p);
-    }
-    // Resolve each node's display name once, deterministically, tracking sibling
-    // collisions per parent. `usedBySibling` maps a parent key -> set of names
-    // already taken under that parent. The bucket key is the node's parent ONLY
-    // when that parent is actually present in `byId`; otherwise (null parent, or
-    // an orphan whose parent is outside the input set) the node buckets at
-    // `"__root__"`. This is critical: orphans land at the vault root (see
-    // `folderSegmentsFor`), so they MUST share the root bucket with real root
-    // pages to be disambiguated against each other here — making `nameById` final
-    // before any `segments` are computed, so no ancestor name can drift later.
-    const usedBySibling = new Map();
-    const nameById = new Map();
-    for (const p of pages) {
-        if (p && p.id && !nameById.has(p.id)) {
-            const parentKey = p.parentPageId && byId.has(p.parentPageId) ? p.parentPageId : "__root__";
-            nameById.set(p.id, nameForNode(p, parentKey, usedBySibling));
-        }
-    }
-    // Every id we index above MUST get a resolved name; this helper returns it
-    // and THROWS if it is somehow absent, rather than silently recomputing a
-    // DIFFERENT, non-disambiguated name (which would desync a folder segment from
-    // its target file).
-    const nameOf = (id) => {
-        const name = nameById.get(id);
-        if (name === undefined) {
-            throw new Error(`buildVaultLayout: no resolved name for page id ${id}`);
-        }
-        return name;
-    };
-    // Build the folder path for a page by walking parentPageId to the root. The
-    // page's OWN name is the file stem; its ancestors become folders. A `visited`
-    // guard prevents an infinite loop on a malformed parent cycle.
-    const folderSegmentsFor = (node) => {
-        const ancestors = [];
-        const visited = new Set();
-        let current = node.parentPageId
-            ? byId.get(node.parentPageId)
-            : undefined;
-        while (current && current.id && !visited.has(current.id)) {
-            visited.add(current.id);
-            ancestors.unshift(nameOf(current.id));
-            current = current.parentPageId
-                ? byId.get(current.parentPageId)
-                : undefined;
-        }
-        return ancestors;
-    };
-    // First pass: compute the provisional { segments, stem } for every node.
-    const layout = new Map();
-    for (const p of pages) {
-        if (!p || !p.id || layout.has(p.id))
-            continue;
-        layout.set(p.id, {
-            segments: folderSegmentsFor(p),
-            stem: nameOf(p.id),
-        });
-    }
-    // FOLDER-NOTE transform (native-Obsidian layout): a page WITH CHILDREN lives at
-    // `<…>/<stem>/<stem>.md` — its body is the folder-note INSIDE its own folder
-    // (LostPaul Folder Notes convention), and its children sit alongside it in that
-    // folder. A leaf stays `<…>/<stem>.md`. Children's segments already point into
-    // the parent's folder (folderSegmentsFor walks ancestor NAMES), so only the
-    // parent's own file relocates here; the sibling name pass above already made
-    // the parent name unique, so folder == file name stays consistent.
-    for (const p of pages) {
-        if (!p || !p.id)
-            continue;
-        const entry = layout.get(p.id);
-        if (entry && p.hasChildren) {
-            entry.segments = [...entry.segments, entry.stem];
-        }
-    }
-    // Final full-path uniqueness pass — a belt-and-suspenders safety net. Note
-    // that cross-bucket (orphan/root) collisions are now resolved in the name pass
-    // above (orphans share the "__root__" bucket), so ancestor names are final
-    // before `segments` are built and this pass should rarely/never re-stem an
-    // ancestor. It only re-stems the colliding LATER leaf via the sanitized
-    // slugId/id, then (if still colliding) appends the id.
-    //
-    // Process FOLDER-NOTES (pages with children) FIRST so a parent claims its
-    // canonical `<name>/<name>.md` before a same-named CHILD — the child (a leaf)
-    // is the one that disambiguates, never the folder-note.
-    const usedPaths = new Set();
-    const seenIds = new Set();
-    const pathKey = (e) => [...e.segments, e.stem].join("/");
-    const ordered = pages
-        .filter((p) => Boolean(p && p.id))
-        .sort((a, b) => Number(Boolean(b.hasChildren)) - Number(Boolean(a.hasChildren)));
-    for (const p of ordered) {
-        if (seenIds.has(p.id))
-            continue;
-        seenIds.add(p.id);
-        const entry = layout.get(p.id);
-        if (!entry)
-            continue;
-        if (usedPaths.has(pathKey(entry))) {
-            // First attempt: disambiguate the stem with the sanitized slugId (or id).
-            entry.stem = disambiguate(entry.stem, sanitizeTitle(p.slugId ?? p.id));
-            if (usedPaths.has(pathKey(entry))) {
-                // Still colliding: append the (sanitized) id as a last resort. The id
-                // is globally unique, so this always resolves the collision.
-                entry.stem = disambiguate(entry.stem, sanitizeTitle(p.id));
-            }
-        }
-        usedPaths.add(pathKey(entry));
-    }
-    return layout;
-}
-/**
- * Compute a deterministic, collision-free name for a node among its SIBLINGS.
- * `usedBySibling` maps a parent key -> set of names already taken, so two
- * siblings that sanitize to the same name get a stable ` ~slugId` suffix
- * (SPEC §12). The suffix is itself passed through `sanitizeTitle`, because the
- * slugId/id is a second untrusted-data channel that must never leak a path
- * separator into the name. `parentKey` is supplied by the caller (it resolves
- * to `"__root__"` for root pages AND for orphans whose parent is outside the
- * input set, so they share one bucket). The name is COSMETIC; identity lives in
- * the meta block.
- */
-function nameForNode(node, parentKey, usedBySibling) {
-    let used = usedBySibling.get(parentKey);
-    if (!used) {
-        used = new Set();
-        usedBySibling.set(parentKey, used);
-    }
-    let name = sanitizeTitle(node.title ?? "");
-    if (used.has(name)) {
-        // Sibling collision: disambiguate with the stable, sanitized slugId (fall
-        // back to the sanitized pageId if no slugId is present).
-        name = disambiguate(name, sanitizeTitle(node.slugId ?? node.id));
-    }
-    used.add(name);
-    return name;
-}

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

@@ -1,13 +0,0 @@
-/**
- * Stable hash of a page's markdown BODY (SPEC §10 "хэш тела"). Deterministic:
- * the same input string always yields the same digest, a different input a
- * different one. Used to recognize our own write later (loop suppression).
- *
- * We hash the body STRING as-is (UTF-8) with SHA-256 and return lowercase hex.
- * SPEC §10 keys on the body hash rather than file bytes; callers decide WHAT
- * counts as "the body" (here it is the exact string passed in — typically the
- * self-contained markdown that was pushed). No normalization is applied: the
- * caller is responsible for passing a canonical/stable representation if it
- * wants hash equality across cosmetic-only differences.
- */
-export declare function bodyHash(markdownBody: string): string;

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

@@ -1,136 +0,0 @@
-import type { GitSyncClient } from "./client.types.js";
-import { type PageNode } from "./layout.js";
-import { VaultGit } from "./git.js";
-import { type MovedEntry, type DeletionDecision } from "./reconcile.js";
-/**
- * Injectable IO for `readExisting` (R-Pull-1, test-strategy report §5). The real
- * `main` wires these to `git.listTrackedFiles("*.md")` and an `fs.readFile`
- * rooted at the vault; tests pass fakes so the parsing/skip rules are unit-
- * testable without a real git repo or filesystem.
- */
-export interface ReadExistingDeps {
-    /** List tracked .md paths (forward-slash, vault-relative). */
-    listTracked: () => Promise<string[]>;
-    /** Read a tracked file's text by its (forward-slash) vault-relative path. */
-    readFile: (relPath: string) => Promise<string>;
-}
-/**
- * Read every tracked .md file in the vault and recover `{ pageId, relPath }` from
- * its `gitmost_id` frontmatter (native-Obsidian format). Files without a
- * `gitmost_id` are skipped (they are not engine-tracked pages yet — e.g. a stray
- * hand-written Obsidian file; PUSH adopts those separately).
- *
- * The IO is injected (R-Pull-1) so this is testable with fakes. Skip rules:
- *   - a `readFile` rejection (tracked but missing on disk, a mid-operation race)
- *     -> skipped, NOT thrown; the next pull converges;
- *   - no `gitmost_id` frontmatter (`parsePageFile` -> id null) -> skipped.
- */
-export declare function readExisting(deps: ReadExistingDeps): Promise<{
-    pageId: string;
-    relPath: string;
-}[]>;
-/**
- * Input to the PURE `computePullActions` (R-Pull-2). All data, no IO: the live
- * tree nodes + completeness flag (from `listSpaceTree`) and the parsed
- * `existing` tracked files (from `readExisting`).
- */
-export interface PullActionsInput {
-    /** Live page nodes for the space (from `listSpaceTree`). */
-    pages: PageNode[];
-    /** Whether the live tree fetch was COMPLETE (SPEC §8 suppression). */
-    treeComplete: boolean;
-    /** Parsed tracked files: `{ pageId, relPath }` (from `readExisting`). */
-    existing: {
-        pageId: string;
-        relPath: string;
-    }[];
-}
-/**
- * The PURE decisions object computed by `computePullActions` (no IO). It holds
- * the reconciliation plan plus the SPEC §8 absence-deletion decision, with the
- * suppression already folded in: `toDelete` is the POST-suppression set the
- * caller should actually remove (empty when `deletionDecision.apply` is false).
- */
-export interface PullActions {
-    /** Pages to (re)write at their relPath (add + update + move target). */
-    toWrite: {
-        pageId: string;
-        relPath: string;
-    }[];
-    /** Moves: write new path, then remove old path (only on a successful write). */
-    moved: MovedEntry[];
-    /**
-     * Absence-based paths to delete AFTER suppression. Empty when the decision
-     * suppressed deletions this cycle, so the caller can apply it unconditionally.
-     */
-    toDelete: string[];
-    /** Why absence deletions were (or were not) applied (for logging + tests). */
-    deletionDecision: DeletionDecision;
-    /** Tracked-file count (for the suppression log messages). */
-    existingCount: number;
-    /** Planned absence-delete count BEFORE suppression (for the log message). */
-    plannedDeleteCount: number;
-}
-/**
- * PURE pull-action planner (R-Pull-2, test-strategy report §5). Takes the live
- * tree nodes + completeness + existing tracked files and returns the full set of
- * decisions with NO IO:
- *
- *   - builds the vault layout (deterministic relPath per live page),
- *   - `planReconciliation` -> toWrite / moved / absence-toDelete,
- *   - `decideAbsenceDeletions` -> the SPEC §8 suppression (incomplete-fetch +
- *     empty-live + mass-delete guard), folded IN here so `toDelete` is the
- *     POST-suppression set (empty when suppressed).
- *
- * Moves are NOT governed by the suppression: a moved page is present in `live`,
- * so its old-path removal is real (the caller still gates it on the write
- * succeeding). The expensive content fetch / file write / git ops happen in the
- * thin `applyPullActions`.
- */
-export declare function computePullActions(input: PullActionsInput): PullActions;
-/**
- * Injectable IO for `applyPullActions` (R-Pull-2). The real `main` wires these
- * to the live client, the vault git wrapper, and `node:fs/promises`; tests pass
- * fakes that RECORD calls so the ordering + the move-on-success data-loss guard
- * are testable without real git/fs/network.
- */
-export interface ApplyPullActionsDeps {
-    client: Pick<GitSyncClient, "getPageJson">;
-    git: Pick<VaultGit, "stageAll" | "commit" | "checkout" | "merge">;
-    /** Write a file by ABSOLUTE path (mkdir of the parent is done internally). */
-    writeFile: (absPath: string, text: string) => Promise<void>;
-    /** Recursive mkdir of an ABSOLUTE directory path. */
-    mkdir: (absDir: string) => Promise<void>;
-    /** Remove a file by ABSOLUTE path (force: a missing file is a no-op). */
-    rm: (absPath: string) => Promise<void>;
-}
-/** Outcome counters from `applyPullActions` (for the summary + tests). */
-export interface ApplyResult {
-    written: number;
-    movedApplied: number;
-    deleted: number;
-    failed: number;
-    committed: boolean;
-    merge: {
-        ok: boolean;
-        conflict: boolean;
-        output: string;
-    };
-}
-/**
- * THIN IO applier (R-Pull-2). Performs the side effects in the EXACT current
- * order, with all the original safety guards preserved bit-for-bit:
- *
- *   1. for each `toWrite`: fetch content (`client.getPageJson`) -> stabilize
- *      (normalize-on-write fixpoint, SPEC §11) -> mkdir + write. One bad page
- *      never aborts the pull (bounded-concurrency pool, fault-tolerant).
- *   2. apply MOVE old-path removals — ONLY when the planner marked the old path
- *      removable AND the new-path write SUCCEEDED (the ⭐ data-loss guard: a
- *      failed move-write keeps the old path so the page never vanishes).
- *   3. apply (post-suppression) absence deletes.
- *   4. stageAll + commit on `docmost` (subject from ACTUAL written/deleted
- *      counts) + checkout main + merge docmost (conflicts surfaced, SPEC §9).
- *
- * `vaultRoot` roots the relPath -> absolute-path conversion for the fs deps.
- */
-export declare function applyPullActions(deps: ApplyPullActionsDeps, actions: PullActions, vaultRoot: string): Promise<ApplyResult>;

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

@@ -1,284 +0,0 @@
-/**
- * Pull cycle — Docmost -> vault (SPEC §6 "Docmost -> ФС").
- *
- * This increment turns the read-only mirror into the git-backed pull cycle:
- *
- *   1. ensureRepo(vault); refuse if a merge is in progress (SPEC §9/§12);
- *      ensureBranch("docmost", "main")   (SPEC §5 branches)
- *   2. checkout docmost
- *   3. fetch the live tree (listSpaceTree -> {pages, complete}) -> compute the
- *      desired `live` files (relPath via the pure sanitize/disambiguation layout)
- *   4. parse `existing` tracked .md files (pageId + relPath from gitmost_id frontmatter)
- *   5. plan = planReconciliation(live, existing)   (pure, SPEC §5/§8); toDelete
- *      is absence-only, moves are separate
- *   6. decideAbsenceDeletions: SUPPRESS absence deletions on an incomplete tree
- *      fetch (SPEC §8) and behind the mass-delete guard (defense in depth)
- *   7. write each live page in its fixpoint form (normalize-on-write, SPEC §11);
- *      apply moved-old-path removals (only when the move write SUCCEEDED) and
- *      absence-delete removals (only when the decision allowed them)
- *   8. stageAll + commit on `docmost` with the provenance trailer (SPEC §7.3)
- *   9. checkout main + merge docmost (conflicts are surfaced, NOT auto-resolved,
- *      SPEC §9); push is deferred (SPEC §7)
- *  10. one-line summary
- *
- * DIRECTION IS Docmost -> vault ONLY. Nothing here ever writes to Docmost
- * (read-only: listSpaceTree + getPageJson). All git operations run against
- * the vault repo (`cwd = vaultPath`), never the source repo (see ./git.ts).
- *
- * The client seam is the native `GitSyncClient` (`Pick<GitSyncClient, ...>`);
- * the gitmost server drives the engine in-process (there is no standalone CLI
- * entry point).
- */
-import { dirname } from "node:path";
-import { sep } from "node:path";
-import { parsePageFile, serializePageFile } from "../lib/page-file.js";
-import { buildVaultLayout } from "./layout.js";
-import { BOT_AUTHOR_NAME, BOT_AUTHOR_EMAIL, DEFAULT_BRANCH, } from "./git.js";
-import { planReconciliation, decideAbsenceDeletions, } from "./reconcile.js";
-import { stabilizePageBody } from "./stabilize.js";
-// Engine-only mirror branch (SPEC §5): the engine writes here, humans never do.
-const DOCMOST_BRANCH = "docmost";
-// Machine-readable provenance the loop-guard keys on (SPEC §7.3 / §12).
-const SOURCE_TRAILER = "Docmost-Sync-Source: docmost";
-// Number of pages fetched/stabilized concurrently. Bounded so a large space
-// does not open thousands of simultaneous requests/conversions at once.
-const CONCURRENCY = 6;
-// How often to log incremental progress (every N completed pages).
-const PROGRESS_EVERY = 25;
-/** Convert a vault-relative path (forward-slash) to an absolute FS path. */
-function relToAbs(vaultRoot, relPath) {
-    return [vaultRoot, ...relPath.split("/")].join("/");
-}
-/** Convert an absolute/relative segment list under the vault to a relPath. */
-function segmentsToRelPath(segments, stem) {
-    return [...segments, `${stem}.md`].join("/");
-}
-/**
- * Read every tracked .md file in the vault and recover `{ pageId, relPath }` from
- * its `gitmost_id` frontmatter (native-Obsidian format). Files without a
- * `gitmost_id` are skipped (they are not engine-tracked pages yet — e.g. a stray
- * hand-written Obsidian file; PUSH adopts those separately).
- *
- * The IO is injected (R-Pull-1) so this is testable with fakes. Skip rules:
- *   - a `readFile` rejection (tracked but missing on disk, a mid-operation race)
- *     -> skipped, NOT thrown; the next pull converges;
- *   - no `gitmost_id` frontmatter (`parsePageFile` -> id null) -> skipped.
- */
-export async function readExisting(deps) {
-    const tracked = await deps.listTracked();
-    const existing = [];
-    for (const relPath of tracked) {
-        // git ls-files always emits forward-slash paths; normalize just in case.
-        const rel = relPath.split(sep).join("/");
-        let text;
-        try {
-            text = await deps.readFile(rel);
-        }
-        catch {
-            // Tracked but missing on disk (mid-operation race) — skip; the next pull
-            // converges.
-            continue;
-        }
-        const { id } = parsePageFile(text);
-        if (id)
-            existing.push({ pageId: id, relPath: rel });
-    }
-    return existing;
-}
-/**
- * PURE pull-action planner (R-Pull-2, test-strategy report §5). Takes the live
- * tree nodes + completeness + existing tracked files and returns the full set of
- * decisions with NO IO:
- *
- *   - builds the vault layout (deterministic relPath per live page),
- *   - `planReconciliation` -> toWrite / moved / absence-toDelete,
- *   - `decideAbsenceDeletions` -> the SPEC §8 suppression (incomplete-fetch +
- *     empty-live + mass-delete guard), folded IN here so `toDelete` is the
- *     POST-suppression set (empty when suppressed).
- *
- * Moves are NOT governed by the suppression: a moved page is present in `live`,
- * so its old-path removal is real (the caller still gates it on the write
- * succeeding). The expensive content fetch / file write / git ops happen in the
- * thin `applyPullActions`.
- */
-export function computePullActions(input) {
-    const { pages, treeComplete, existing } = input;
-    const layout = buildVaultLayout(pages);
-    const live = [];
-    for (const p of pages) {
-        if (!p || !p.id)
-            continue;
-        const entry = layout.get(p.id);
-        if (!entry)
-            continue;
-        live.push({
-            pageId: p.id,
-            relPath: segmentsToRelPath(entry.segments, entry.stem),
-        });
-    }
-    // Plan reconciliation (pure). `plan.toDelete` is ABSENCE-based only;
-    // `plan.moved` carries move old-path removals separately.
-    const plan = planReconciliation(live, existing);
-    // Decide whether the ABSENCE-based deletions may be applied this cycle
-    // (SPEC §8): incomplete-fetch suppression + empty-live + mass-delete guard.
-    // Moves are NOT governed by this.
-    const deletionDecision = decideAbsenceDeletions({
-        treeComplete,
-        liveCount: live.length,
-        existingCount: existing.length,
-        deleteCount: plan.toDelete.length,
-    });
-    return {
-        toWrite: plan.toWrite,
-        moved: plan.moved,
-        // Fold the suppression in: a suppressed cycle deletes nothing.
-        toDelete: deletionDecision.apply ? plan.toDelete : [],
-        deletionDecision,
-        existingCount: existing.length,
-        plannedDeleteCount: plan.toDelete.length,
-    };
-}
-/**
- * THIN IO applier (R-Pull-2). Performs the side effects in the EXACT current
- * order, with all the original safety guards preserved bit-for-bit:
- *
- *   1. for each `toWrite`: fetch content (`client.getPageJson`) -> stabilize
- *      (normalize-on-write fixpoint, SPEC §11) -> mkdir + write. One bad page
- *      never aborts the pull (bounded-concurrency pool, fault-tolerant).
- *   2. apply MOVE old-path removals — ONLY when the planner marked the old path
- *      removable AND the new-path write SUCCEEDED (the ⭐ data-loss guard: a
- *      failed move-write keeps the old path so the page never vanishes).
- *   3. apply (post-suppression) absence deletes.
- *   4. stageAll + commit on `docmost` (subject from ACTUAL written/deleted
- *      counts) + checkout main + merge docmost (conflicts surfaced, SPEC §9).
- *
- * `vaultRoot` roots the relPath -> absolute-path conversion for the fs deps.
- */
-export async function applyPullActions(deps, actions, vaultRoot) {
-    const { client, git } = deps;
-    // Emit the SPEC §8 suppression warnings (preserved from the original `main`).
-    const decision = actions.deletionDecision;
-    if (!decision.apply) {
-        if (decision.reason === "incomplete-fetch") {
-            console.warn("pull: tree fetch incomplete — deletions suppressed this cycle (SPEC §8)");
-        }
-        else if (decision.reason === "empty-live") {
-            console.warn(`pull: live fetch returned 0 pages but ${actions.existingCount} file(s) are ` +
-                `tracked — deletions suppressed this cycle (SPEC §8). Re-run when ` +
-                `Docmost is reachable.`);
-        }
-        else {
-            console.warn(`pull: plan would delete ${actions.plannedDeleteCount} of ${actions.existingCount} ` +
-                `tracked file(s) (mass-delete guard) — deletions suppressed this ` +
-                `cycle (SPEC §8). Verify the live Docmost tree, then re-run.`);
-        }
-    }
-    // 1. Write each live page in its fixpoint form (normalize-on-write, SPEC §11).
-    let written = 0;
-    let failed = 0;
-    let completed = 0;
-    let nextIndex = 0;
-    // pageIds whose write FAILED. A moved page whose new-path write failed must
-    // NOT have its old path removed (otherwise the page vanishes entirely).
-    const failedPageIds = new Set();
-    const writeOne = async (w) => {
-        try {
-            const page = await client.getPageJson(w.pageId);
-            // Native-Obsidian format: a minimal `gitmost_id` frontmatter + the fixpoint
-            // markdown body. title/parent/space are DERIVED (filename / folder / repo),
-            // so nothing but the pageId is persisted as meta.
-            const text = serializePageFile(page.id, await stabilizePageBody(page.content));
-            const abs = relToAbs(vaultRoot, w.relPath);
-            await deps.mkdir(dirname(abs));
-            await deps.writeFile(abs, text);
-            written++;
-        }
-        catch (err) {
-            failed++;
-            failedPageIds.add(w.pageId);
-            console.error(`pull: failed page ${w.pageId}:`, err instanceof Error ? err.message : String(err));
-        }
-        finally {
-            completed++;
-            if (completed % PROGRESS_EVERY === 0) {
-                console.log(`pulled ${completed}/${actions.toWrite.length}`);
-            }
-        }
-    };
-    // Bounded-concurrency pool (dependency-free): a fixed set of runners each
-    // take the next index until the write list is exhausted. One bad page never
-    // aborts the whole pull (mirrors the fault-tolerant tree walk).
-    const runner = async () => {
-        while (true) {
-            const i = nextIndex++;
-            if (i >= actions.toWrite.length)
-                return;
-            await writeOne(actions.toWrite[i]);
-        }
-    };
-    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, actions.toWrite.length) || 1 }, () => runner()));
-    // Helper: `rm` with force:true is a no-op if the file is already gone.
-    const removePath = async (rel, what) => {
-        try {
-            await deps.rm(relToAbs(vaultRoot, rel));
-            return true;
-        }
-        catch (err) {
-            console.error(`pull: failed to ${what} ${rel}:`, err instanceof Error ? err.message : String(err));
-            return false;
-        }
-    };
-    // 2. Apply MOVE old-path removals. A moved page IS present in `live`, so its
-    //    old path is genuinely stale — NOT subject to the incomplete-fetch
-    //    suppression. BUT only remove the old path when (a) the planner marked it
-    //    removable (not reused by another live page) AND (b) the new-path write
-    //    actually SUCCEEDED — otherwise we would delete the only copy of a page
-    //    whose move-write failed (⭐ data-loss guard).
-    let movedApplied = 0;
-    for (const m of actions.moved) {
-        if (!m.removeOldPath)
-            continue;
-        if (failedPageIds.has(m.pageId)) {
-            console.warn(`pull: move write for ${m.pageId} failed — keeping old path ` +
-                `${m.fromRelPath} (SPEC §8)`);
-            continue;
-        }
-        if (await removePath(m.fromRelPath, "remove moved old path"))
-            movedApplied++;
-    }
-    // 3. Apply ABSENCE-based deletions — `actions.toDelete` is ALREADY the
-    //    post-suppression set (empty when the decision suppressed them, SPEC §8).
-    let deleted = 0;
-    for (const rel of actions.toDelete) {
-        if (await removePath(rel, "delete"))
-            deleted++;
-    }
-    // 4. Stage + commit on `docmost` (only if there is something to commit).
-    //    Deterministic stabilized output means unchanged pages produce identical
-    //    bytes -> git sees no diff -> no churn (SPEC §11). The subject reflects the
-    //    ACTUAL work applied (pages written + files deleted), not the planned size,
-    //    so a run with failures does not over-report (SPEC §5 nit).
-    const subject = deleted > 0
-        ? `docmost: sync ${written} page(s), ${deleted} deleted`
-        : `docmost: sync ${written} page(s)`;
-    await git.stageAll();
-    const committed = await git.commit(subject, {
-        authorName: BOT_AUTHOR_NAME,
-        authorEmail: BOT_AUTHOR_EMAIL,
-        trailers: [SOURCE_TRAILER],
-    });
-    // Merge docmost -> main. Conflicts are surfaced and left in git (SPEC §9);
-    // we never push to Docmost. Push to a git remote is deferred (SPEC §7).
-    await git.checkout(DEFAULT_BRANCH);
-    const merge = await git.merge(DOCMOST_BRANCH);
-    if (merge.conflict) {
-        console.error("pull: merge of docmost -> main CONFLICTED. Conflict markers were left " +
-            "in the vault for manual resolution (SPEC §9). Nothing is pushed to " +
-            "Docmost (read-only). Resolve locally, then re-run.");
-    }
-    else if (!merge.ok) {
-        console.error(`pull: merge of docmost -> main failed: ${merge.output}`);
-    }
-    console.log("pull: git push to remote is DEFERRED in this increment (SPEC §7).");
-    return { written, movedApplied, deleted, failed, committed, merge };
-}

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

@@ -1,504 +0,0 @@
-/**
- * Push cycle — vault -> Docmost (SPEC §6 "ФС → Docmost"), FIRST increment.
- *
- * This module mirrors the structure of `./pull.ts`: a set of VaultGit diff/ref
- * primitives (in `./git.ts`), a PURE planner (`computePushActions`) that turns
- * a git diff into a classified action set with NO IO, and a THIN injectable
- * applier (`applyPushActions`) exercised in tests via fakes only.
- *
- * Direction is vault -> Docmost. The diff is `main` against
- * `refs/docmost/last-pushed` (SPEC §6 step 2); each `A`/`M`/`D`/`R` row is
- * translated into a Docmost mutation by `pageId` identity (SPEC §4):
- *   - A without pageId   -> create_page (then write the assigned pageId back).
- *   - A with    pageId   -> update (restored/copied file; the page already exists).
- *   - M                  -> update content (collab/Yjs path, SPEC §2/§15.6).
- *   - D                  -> delete_page (pageId recovered from the PRE-IMAGE meta).
- *   - R                  -> rename/move (CLASSIFIED here, APPLIED in push #3).
- *
- * MOVE/RENAME APPLY (push #3) — DONE here. `classifyRenameMoves` (PURE) resolves
- * each `renamesMoves` entry into the Docmost op(s) it needs, comparing the PATH-
- * derived parent (SPEC §5: the file path is the source of truth for tree
- * position, NOT stale `meta.parentPageId`) and the meta title; `applyPushActions`
- * then calls `move_page` / `rename_page` (both for a reparent+retitle), or
- * records a NO-OP for a cosmetic local-only file-path rename.
- *
- * The client seam is the native `GitSyncClient` (`Pick<GitSyncClient, ...>`);
- * the gitmost server drives the engine in-process (there is no standalone CLI
- * entry point).
- */
-import { type DocmostMdMeta } from "../lib/index.js";
-import type { GitSyncClient } from "./client.types.js";
-import type { DiffEntry } from "./git.js";
-import { VaultGit } from "./git.js";
-import { type Settings } from "./settings.js";
-export type { DiffEntry } from "./git.js";
-/** A page to CREATE in Docmost (new local file, meta has no pageId yet). */
-export interface CreateAction {
-    /** Vault-relative path of the new file. */
-    path: string;
-}
-/** A page whose CONTENT changed (meta carries the existing pageId). */
-export interface UpdateAction {
-    pageId: string;
-    /** Vault-relative path of the changed file. */
-    path: string;
-}
-/** A page to soft-delete in Docmost (Trash, SPEC §8). */
-export interface DeleteAction {
-    pageId: string;
-}
-/** A renamed/moved page (same pageId, new path). Resolution DEFERRED. */
-export interface RenameMoveAction {
-    pageId: string;
-    oldPath: string;
-    newPath: string;
-}
-/**
- * A CLASSIFIED rename/move (push #3): a `RenameMoveAction` resolved into the
- * Docmost op(s) it actually needs. The file PATH is the source of truth for tree
- * position (SPEC §5: "истина связи — pageId, не путь" — the path is COSMETIC and
- * LOCAL, the page identity is its pageId), so we compare the RESOLVED parent of
- * the new path against the resolved parent of the old path, and the title in the
- * current meta against the title in the previous meta. Each sub-op is emitted
- * ONLY when something real changed:
- *   - `move`  — the resolved parent page changed (reparent in Docmost). A `null`
- *     `parentPageId` means the new parent is ROOT (the file sits at the space
- *     root, no enclosing folder).
- *   - `rename` — the page title changed (a pure title edit in Docmost).
- *   - `noop`  — neither changed: a purely LOCAL file-path rename (same parent,
- *     same title). The page identity is its pageId, so Docmost is NOT called.
- * `move` and `rename` are independent and may BOTH be present (reparent + retitle).
- */
-export interface RenameMoveActionClassified {
-    pageId: string;
-    oldPath: string;
-    newPath: string;
-    /** Present iff the resolved parent changed -> `move_page` (reparent). */
-    move?: {
-        parentPageId: string | null;
-    };
-    /** Present iff the title changed -> `rename_page` (title-only). */
-    rename?: {
-        title: string;
-    };
-    /** True iff neither parent nor title changed (cosmetic local-only rename). */
-    noop?: true;
-}
-/**
- * Injected resolvers for the PURE `classifyRenameMoves` (push #3). Both are PURE
- * given a path + side; the real `main` (a follow-up) wires them to the file tree
- * (`readFile` for `current`, `git.showFileAtRef` for `prev`), tests pass plain
- * lookups. SPEC §5 path-as-truth:
- *   - `metaAt`: the file's synthetic native meta at that side (title from the
- *     filename, pageId from the `gitmost_id` frontmatter).
- *   - `resolveParentPageId`: the pageId of the page whose FILE is the parent
- *     FOLDER's `.md` (one level up from the given path), or `null` for ROOT.
- */
-export interface ClassifyRenameMovesDeps {
-    metaAt: (path: string, side: MetaSide) => DocmostMdMeta | null;
-    resolveParentPageId: (path: string, side: MetaSide) => string | null;
-}
-/**
- * PURE classifier for the `renamesMoves` produced by `computePushActions`
- * (push #3, SPEC §5/§6/§8). Resolves each `{pageId, oldPath, newPath}` into the
- * Docmost op(s) it needs, with NO IO (both resolvers are injected).
- *
- * SPEC §5 — the file PATH is the source of truth for tree position, NOT the
- * (possibly stale) `meta.parentPageId`. So the NEW parent is resolved from
- * `newPath`'s enclosing folder, and the OLD parent from `oldPath`'s enclosing
- * folder, via `deps.resolveParentPageId`. The title comes from the meta.
- *
- * For each entry:
- *   - `newParent = resolveParentPageId(newPath, 'current')`,
- *     `oldParent = resolveParentPageId(oldPath, 'prev')`.
- *   - `newTitle = metaAt(newPath,'current')?.title`,
- *     `oldTitle = metaAt(oldPath,'prev')?.title`.
- *   - include `move` iff `newParent !== oldParent` (a real reparent),
- *   - include `rename` iff `newTitle` is a NON-EMPTY string AND differs from
- *     `oldTitle` (a real title edit; an empty/absent new title is never a rename),
- *   - if NEITHER applies -> `noop: true` (a cosmetic local-only file-path rename;
- *     the page is its pageId, so Docmost is not touched).
- */
-export declare function classifyRenameMoves(renamesMoves: RenameMoveAction[], deps: ClassifyRenameMovesDeps): RenameMoveActionClassified[];
-/** The classified set of push actions (PURE output of `computePushActions`). */
-export interface PushActions {
-    creates: CreateAction[];
-    updates: UpdateAction[];
-    deletes: DeleteAction[];
-    renamesMoves: RenameMoveAction[];
-    /**
-     * Diff rows that could NOT be classified into an action, with a reason — e.g.
-     * a deleted file whose PRE-IMAGE meta carried no recoverable pageId (the
-     * untracked-file guard, SPEC §8: only files that were tracked with a pageId
-     * are deleted in Docmost). Carried so the caller can log them.
-     */
-    skipped: {
-        path: string;
-        status: DiffEntry["status"];
-        reason: string;
-    }[];
-}
-/**
- * Which tree a `metaAt` lookup reads the file's native meta from:
- *   - `current`: the current `main` tree (the live file content) — used for
- *     A/M/R, where the file still exists.
- *   - `prev`: the last-pushed PRE-IMAGE (e.g. `refs/docmost/last-pushed:<path>`)
- *     — used for D, where the file is gone from `main` but its pageId must be
- *     recovered from the version Docmost last knew (SPEC §6/§8).
- */
-export type MetaSide = "current" | "prev";
-/** Input to the PURE planner. `metaAt` is injected (no IO inside the planner). */
-export interface PushActionsInput {
-    /** Diff rows of `main` vs `refs/docmost/last-pushed` (SPEC §6 step 2). */
-    changes: DiffEntry[];
-    /**
-     * Resolve a file's synthetic native meta at a given side, or `null` if the file is
-     * absent there / has no parseable meta. PURE injection: the real `main` reads
-     * the working tree (current) or `git show <last-pushed>:<path>` (prev); tests
-     * pass a plain lookup.
-     */
-    metaAt: (path: string, side: MetaSide) => DocmostMdMeta | null;
-    /**
-     * The pageIds present at ANY path in the current `main` tree (optional). When
-     * given, a deleted file whose pageId still lives somewhere in the tree is NOT
-     * a deletion but a MOVE — guards against trashing a live page when a layout
-     * reshuffle relocated its file (possibly across two cycles, so the matching
-     * add isn't in THIS diff). When omitted, only the in-diff D+A/M coalescing
-     * applies.
-     */
-    currentPageIds?: Set<string>;
-}
-/**
- * PURE push planner (SPEC §4/§6/§8). Classifies each diff row into a Docmost
- * action by `pageId` identity, with NO IO (the `metaAt` resolver is injected).
- *
- * Classification rules:
- *   - `A` (added):
- *       - current meta HAS a pageId  -> UPDATE (a restored/copied file whose
- *         page already exists; we push its content rather than create a dup).
- *       - current meta has NO pageId but HAS a non-empty spaceId -> CREATE (a
- *         brand-new local file; the page does not exist in Docmost yet).
- *       - current meta has NO pageId and NO usable spaceId -> SKIP with reason
- *         `create-without-spaceId`: Docmost `create_page` REQUIRES a spaceId
- *         (§16), and a new local file may carry only partial human meta. We
- *         refuse to create rather than guess a space (SPEC §8 guard spirit).
- *   - `M` (modified): current meta has a pageId -> UPDATE content. (If a modified
- *       file somehow lost its pageId it is skipped — there is nothing to target.)
- *   - `D` (deleted): recover the pageId from the PRE-IMAGE meta (`metaAt(path,
- *       'prev')`) -> DELETE. If no pageId can be recovered, SKIP with a reason
- *       (untracked-file guard, SPEC §8: never delete an untracked page).
- *   - `R` (renamed/moved): same pageId (from current meta), path changed ->
- *       RENAME/MOVE. Resolution of move-vs-rename + the new parentPageId is
- *       DEFERRED to the next increment; here we only record oldPath/newPath/
- *       pageId. If the renamed file has no recoverable pageId it is SKIPPED.
- *       (`C` copy is treated the same as `R` for recording purposes.)
- */
-export declare function computePushActions(input: PushActionsInput): PushActions;
-/** The marker the push direction advances after a successful push (SPEC §5/§6). */
-export declare const LAST_PUSHED_REF = "refs/docmost/last-pushed";
-/**
- * The mirror branch fast-forwarded after a clean push (SPEC §5/§6 step 3). It
- * reflects "what Docmost currently contains"; advancing it to the pushed `main`
- * commit closes the loop so the next pull diffs empty for the pushed pages.
- */
-export declare const DOCMOST_BRANCH = "docmost";
-/**
- * Injectable IO for `applyPushActions`. The real `main` (NEXT increment) wires
- * these to the live client, `node:fs/promises`, and the vault git wrapper; this
- * increment drives them only through FAKES in tests (no live destructive run).
- *   - `client`: the create/update/delete/move/rename subset of `GitSyncClient`.
- *   - `readFile`/`writeFile`: read a changed file's body / write a file back
- *     (by vault-relative path; the applier does not resolve absolute paths so
- *     fakes stay trivial).
- *   - `git`: `updateRef` (advance `refs/docmost/last-pushed`) and
- *     `fastForwardBranch` (advance the `docmost` mirror after a clean push, the
- *     loop-close — SPEC §6 step 3 / §10).
- */
-export interface ApplyPushDeps {
-    client: Pick<GitSyncClient, "importPageMarkdown" | "createPage" | "deletePage" | "movePage" | "renamePage">;
-    /** Read a changed file's full text by its vault-relative path. */
-    readFile: (path: string) => Promise<string>;
-    /** Write a file's full text by its vault-relative path. */
-    writeFile: (path: string, text: string) => Promise<void>;
-    /**
-     * The Docmost spaceId this vault mirrors. A CREATE targets this space (the
-     * native file carries no spaceId — every file in the vault belongs to it), and
-     * it backs the synthetic native meta the classifier reads.
-     */
-    spaceId: string;
-    /**
-     * `updateRef` advances `refs/docmost/last-pushed`; `fastForwardBranch` advances
-     * the `docmost` mirror after a clean push. `showFileAtRef` reads a file's text
-     * at a ref (used by the move/rename classifier to resolve the PREVIOUS parent
-     * folder's `.md` at `refs/docmost/last-pushed`, SPEC §5 path-as-truth).
-     */
-    git: Pick<VaultGit, "updateRef" | "fastForwardBranch" | "showFileAtRef">;
-}
-/** A file whose meta was rewritten with a freshly-assigned pageId (post-create). */
-export interface WrittenBackPage {
-    path: string;
-    pageId: string;
-}
-/**
- * The per-page push record consulted by a FUTURE poll-suppression (SPEC §10): a
- * pulled page whose body hash + `updatedAt` match a record here is OUR OWN write
- * and must not be re-pulled. PRODUCED here; CONSUMED on the pull side later.
- */
-export interface PushedPageRecord {
-    /** The Docmost pageId that was updated/created. */
-    pageId: string;
-    /**
-     * The `updatedAt` from the create/update client result, when the result
-     * exposed one. Absent when the (fake) client did not return it.
-     */
-    updatedAt?: string;
-    /** Stable hash of the markdown BODY that was pushed (SPEC §10 "хэш тела"). */
-    bodyHash: string;
-}
-/**
- * One page whose operation FAILED during apply (SPEC §12 resumability). The bad
- * page is isolated — recorded here — and the rest of the batch still runs; the
- * refs are NOT advanced when there is any failure, so a re-run retries cleanly.
- */
-export interface PushFailure {
-    kind: "update" | "create" | "delete" | "move" | "rename";
-    /** The pageId for update/delete/move/rename; absent for a never-id'd create. */
-    pageId?: string;
-    /** The vault-relative path for create/update/move/rename; absent for delete. */
-    path?: string;
-    /** The error message captured from the thrown error. */
-    error: string;
-}
-/**
- * A rename/move action that resolved to a NO-OP (push #3, SPEC §5): a purely
- * LOCAL file-path rename whose resolved parent AND title are both unchanged. The
- * page identity is its pageId and the path is COSMETIC/local-only, so Docmost is
- * NOT called — the skip is recorded here (with the reason) for logging.
- */
-export interface PushNoop {
-    pageId: string;
-    oldPath: string;
-    newPath: string;
-    /** Why no Docmost op was emitted (currently always a path-only rename). */
-    reason: "path-only-rename";
-}
-/** Structured outcome of `applyPushActions` (counts + write-backs + noops). */
-export interface ApplyPushResult {
-    created: number;
-    updated: number;
-    deleted: number;
-    /** Pages reparented in Docmost via `move_page` (push #3, SPEC §5/§16). */
-    moved: number;
-    /** Pages retitled in Docmost via `rename_page` (push #3, SPEC §5/§6). */
-    renamed: number;
-    /**
-     * Files whose `gitmost_id` frontmatter was written with the pageId Docmost assigned on
-     * create — these now need a FOLLOW-UP commit (the meta on disk changed). The
-     * commit itself is the caller's job (NEXT increment); recorded here so it is
-     * not lost.
-     */
-    writtenBack: WrittenBackPage[];
-    /**
-     * Per-page push records (pageId + optional `updatedAt` + body hash) for every
-     * page successfully updated/created — the §10 loop-guard data a future
-     * poll-suppression (pull side) will consult so it does not re-pull our own
-     * write. Deletes are not included (no body was pushed).
-     */
-    pushed: PushedPageRecord[];
-    /**
-     * Pages whose operation threw — isolated and recorded, the batch continued
-     * (SPEC §12). Non-empty here means the refs were NOT advanced.
-     */
-    failures: PushFailure[];
-    /**
-     * Rename/move actions that resolved to a NO-OP — a purely LOCAL file-path
-     * rename (same parent, same title). NO Docmost call was made for these (SPEC
-     * §5: the page is its pageId, the path is local-only). Recorded for logging.
-     */
-    noops: PushNoop[];
-    /** Diff rows the planner could not classify (carried through for logging). */
-    skipped: PushActions["skipped"];
-    /** Whether `refs/docmost/last-pushed` was advanced (only on a CLEAN push). */
-    lastPushedAdvanced: boolean;
-    /**
-     * Result of fast-forwarding the `docmost` mirror branch after a CLEAN push
-     * (the loop-close, SPEC §6 step 3 / §10). `null` when no advance was attempted
-     * (no `pushedCommit`, or there were failures). `{ ok:false, reason }` when a
-     * non-fast-forward was REFUSED (divergent `docmost` history is never clobbered).
-     */
-    docmostFastForward: {
-        ok: boolean;
-        reason?: string;
-    } | null;
-}
-/**
- * THIN IO applier for the COMMON push cases (create/update/delete). Exercised
- * via FAKES only in this increment — there is no live wiring.
- *
- *   - UPDATE: read the file body, then `client.importPageMarkdown(pageId, body)`.
- *     This is the collab/Yjs write path (SPEC §2/§15.6) — NEVER a raw jsonb
- *     overwrite. The full self-contained markdown (meta + body) is sent as-is;
- *     `importPageMarkdown` parses the meta/body itself.
- *   - CREATE: derive title/spaceId/parentPageId from the file's current meta,
- *     `client.createPage(...)`, take the assigned pageId from the result, and
- *     write it BACK as the file's `gitmost_id` frontmatter (re-serialized via
- *     `serializePageFile`, body preserved) so the file becomes
- *     tracked. The write-back is recorded in `writtenBack` (a follow-up commit
- *     is needed — NEXT increment).
- *   - DELETE: `client.deletePage(pageId)` — soft-delete to Trash (SPEC §8).
- *   - RENAME/MOVE (push #3, SPEC §5/§6/§16): classify each `renamesMoves` entry
- *     with `classifyRenameMoves` (resolvers read the parent FOLDER's `.md` for
- *     the parent pageId — path-as-truth — and the meta for the title), then:
- *       - `move`   -> `client.movePage(pageId, parentPageId, position?)` (reparent;
- *         `position` is UNDEFINED for now — the client supplies a default),
- *       - `rename` -> `client.renamePage(pageId, title)` (title-only),
- *       - BOTH     -> move (reparent) THEN rename (title), in that order,
- *       - `noop`   -> NO client call; recorded in `noops` (a cosmetic local-only
- *         file-path rename: the page is its pageId, the path is local, SPEC §5).
- *
- * FAIL-SAFE / per-page isolation (SPEC §12 resumability). Each page's operation
- * is wrapped in its own try/catch: a single failing page is recorded in
- * `failures[]` (with its kind + pageId/path + error) and the batch CONTINUES —
- * one bad page must never block the rest. Crucially, the refs are advanced ONLY
- * when `failures.length === 0`: a PARTIAL push must NOT advance
- * `refs/docmost/last-pushed` or the `docmost` mirror, so a re-run retries the
- * whole batch cleanly (the already-applied pages are idempotent re-applies).
- *
- * LOOP-CLOSE (SPEC §6 step 3 / §10). After a fully-successful push, when a
- * `pushedCommit` is supplied:
- *   - advance `refs/docmost/last-pushed` to it (what of `main` is in Docmost), AND
- *   - fast-forward the `docmost` mirror branch to it via
- *     `git.fastForwardBranch('docmost', pushedCommit)` — so the mirror reflects
- *     what Docmost now contains and the NEXT pull diffs EMPTY for these pages
- *     (it does not re-pull our own write). The ff is REFUSED (not forced) if
- *     `docmost` is not an ancestor of the pushed commit; the result is surfaced
- *     in `docmostFastForward`. On ANY failure, NEITHER ref is advanced.
- *
- * LOOP-GUARD DATA (SPEC §10). For every page successfully updated/created the
- * result carries a `pushed` record `{ pageId, updatedAt?, bodyHash }` — the body
- * hash of what was pushed plus the write's `updatedAt` (when the client returned
- * one). A future pull-side poll-suppression consults this so it does not re-pull
- * our own write; producing it is in scope here, consuming it is deferred.
- *
- * @param pushedCommit The `main` commit just reflected into Docmost (SHA or
- *   commit-ish). When omitted, NEITHER ref is advanced (e.g. a dry plan).
- */
-export declare function applyPushActions(deps: ApplyPushDeps, actions: PushActions, pushedCommit?: string): Promise<ApplyPushResult>;
-/**
- * SPEC §5 path-as-truth: the parent FOLDER's `.md` file for a vault-relative
- * (forward-slash) path. `buildVaultLayout` puts a page with children at
- * `<...>/Title.md` and nests its children under `<...>/Title/`, so for
- * `newPath = <dir>/Child.md` the parent page's file is `<dir>.md` (the enclosing
- * folder, one level up). A path with NO enclosing folder (`Child.md`, at the
- * space root) has no parent folder file -> `null` (the parent is ROOT).
- */
-export declare function parentFolderFile(path: string): string | null;
-/**
- * Whether a vault path is a Docmost PAGE file (design §"Адопция"): a `.md` file
- * with NO dot-segment anywhere in its path. This excludes `.obsidian/` config,
- * `.trash/`, dotfiles (`.foo.md`), and every non-`.md` file (attachments, JSON,
- * …) — Obsidian owns those; they live in the vault but are never pages. Used to
- * screen the PUSH diff so non-page files are never created/updated/deleted in
- * Docmost (and never get a `gitmost_id` frontmatter written into them).
- */
-export declare function isPageFile(path: string): boolean;
-/**
- * The human ("local") git identity used for engine-made commits on `main` in the
- * push direction (SPEC §7.3). The provenance is carried by the trailer (below),
- * which the loop-guard keys on; the identity is for history readability only.
- * When the vault repo already has a configured `user.name`/`user.email`, git
- * uses that for the working-tree commit; this is the fallback the daemon stamps.
- */
-export declare const LOCAL_AUTHOR_NAME = "Local";
-export declare const LOCAL_AUTHOR_EMAIL = "local@local";
-/** The provenance trailer marking a `main`-side (human/local) commit (SPEC §7.3). */
-export declare const LOCAL_SOURCE_TRAILER = "Docmost-Sync-Source: local";
-/**
- * Injectable deps for `runPush` (mirrors `pull.ts`'s wiring; everything that
- * touches the outside world is here so tests pass fakes). `makeClient` is a
- * FACTORY, not a client — a dry-run must build NO client at all (it is never
- * called), and only `--apply` invokes it.
- */
-export interface PushDeps {
-    settings: Settings;
-    git: Pick<VaultGit, "assertGitAvailable" | "ensureRepo" | "isMergeInProgress" | "checkout" | "stageAll" | "commit" | "readRef" | "revParse" | "diffNameStatus" | "showFileAtRef" | "updateRef" | "fastForwardBranch" | "listTrackedFiles">;
-    /** Build a real client — called ONLY on `--apply`, never on dry-run. */
-    makeClient: (settings: Settings) => ApplyPushDeps["client"];
-    /** Read a file's full text by its vault-relative (forward-slash) path. */
-    readFile: (path: string) => Promise<string>;
-    /** Write a file's full text by its vault-relative path. */
-    writeFile: (path: string, text: string) => Promise<void>;
-    /** Structured logger (defaults to console in `main`; a recorder in tests). */
-    log: (line: string) => void;
-}
-/** The structured outcome of a `runPush` cycle (returned + summarized). */
-export interface PushRunResult {
-    /** Which path ran: `dry-run` (plan only) or `apply` (Docmost mutated). */
-    mode: "dry-run" | "apply";
-    /** Why the cycle stopped before planning, if it did (e.g. a left-over merge). */
-    aborted?: "merge-in-progress";
-    /** The diff base the plan was computed against (`last-pushed` else `docmost`). */
-    base?: {
-        ref: string;
-        source: "last-pushed" | "docmost";
-        sha: string | null;
-    };
-    /** The `main` commit the plan targets (the would-be pushed commit). */
-    pushedCommit?: string;
-    /** Planned action counts from the PURE planner (present once a plan was built). */
-    planned?: {
-        creates: number;
-        updates: number;
-        deletes: number;
-        renamesMoves: number;
-        skipped: number;
-    };
-    /** The applier's structured result — ONLY present on the `--apply` path. */
-    applied?: ApplyPushResult;
-    /**
-     * True when `applyPushActions` REFUSED to fast-forward a divergent `docmost`
-     * mirror (SPEC §5 invariant broken). Escalated (logged prominently) and folded
-     * into the CLI's non-zero exit.
-     */
-    divergentDocmost?: boolean;
-    /** Per-page failures from the applier (empty/absent on a clean run). */
-    failures?: PushFailure[];
-}
-/**
- * Run one FS->Docmost push cycle (SPEC §6 "ФС → Docmost"), DRY-RUN BY DEFAULT.
- *
- * Steps (mirrors `pull.ts`):
- *   1. Preflight git: `assertGitAvailable` + `ensureRepo`; ABORT (clear message +
- *      non-zero-ish result) if a merge is in progress — never push on top of an
- *      unresolved conflict (SPEC §9/§12). Conflict markers must NEVER reach
- *      Docmost (SPEC §9).
- *   2. Checkout `main` (the human-facing branch the push reads from).
- *   3. Commit the human's pending working-tree changes on `main` with the
- *      `local` provenance trailer (SPEC §7.3). A no-op when nothing changed.
- *   4. Pick the diff BASE: `refs/docmost/last-pushed` if it resolves, else the
- *      `docmost` mirror branch (what Docmost currently has). Resolve `main`.
- *   5. `diffNameStatus(base, main)` -> changes; build the `metaAt(path, side)`
- *      resolver (current = working tree, prev = `git show <base>:<path>`); run
- *      the PURE `computePushActions`.
- *   6. DRY-RUN (default): LOG the full plan and RETURN — NO client, NO Docmost
- *      calls, NO ref advance.
- *   7. `--apply`: build the client, run `applyPushActions(..., pushedCommit=main)`,
- *      then (a) if any pageIds were written back (creates), commit them on `main`
- *      with the `local` trailer and RE-advance `refs/docmost/last-pushed` to the
- *      new commit so the recorded pageIds are persisted in what Docmost mirrors;
- *      (b) ESCALATE a divergent-`docmost` ff refusal (SPEC §5) with a prominent
- *      WARNING and a non-zero-ish flag. Then log a one-line summary.
- */
-export declare function runPush(deps: PushDeps, opts: {
-    dryRun: boolean;
-}): Promise<PushRunResult>;
-/** Parsed `push` CLI flags. DRY-RUN is the default; `--apply` opts into writes. */
-export interface PushParsedArgs {
-    /** True when `--apply` was passed (the ONLY path that writes to Docmost). */
-    apply: boolean;
-}
-/**
- * Parse the `push` CLI flags. SAFE BY DEFAULT: without `--apply` the run is a
- * DRY-RUN (plan only). Exported so the flag handling is unit-testable.
- */
-export declare function parseArgs(argv: string[]): PushParsedArgs;

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

@@ -1,971 +0,0 @@
-import { parsePageFile, serializePageFile } from "../lib/page-file.js";
-import { DEFAULT_BRANCH } from "./git.js";
-import { bodyHash } from "./loop-guard.js";
-/**
- * PURE classifier for the `renamesMoves` produced by `computePushActions`
- * (push #3, SPEC §5/§6/§8). Resolves each `{pageId, oldPath, newPath}` into the
- * Docmost op(s) it needs, with NO IO (both resolvers are injected).
- *
- * SPEC §5 — the file PATH is the source of truth for tree position, NOT the
- * (possibly stale) `meta.parentPageId`. So the NEW parent is resolved from
- * `newPath`'s enclosing folder, and the OLD parent from `oldPath`'s enclosing
- * folder, via `deps.resolveParentPageId`. The title comes from the meta.
- *
- * For each entry:
- *   - `newParent = resolveParentPageId(newPath, 'current')`,
- *     `oldParent = resolveParentPageId(oldPath, 'prev')`.
- *   - `newTitle = metaAt(newPath,'current')?.title`,
- *     `oldTitle = metaAt(oldPath,'prev')?.title`.
- *   - include `move` iff `newParent !== oldParent` (a real reparent),
- *   - include `rename` iff `newTitle` is a NON-EMPTY string AND differs from
- *     `oldTitle` (a real title edit; an empty/absent new title is never a rename),
- *   - if NEITHER applies -> `noop: true` (a cosmetic local-only file-path rename;
- *     the page is its pageId, so Docmost is not touched).
- */
-export function classifyRenameMoves(renamesMoves, deps) {
-    return renamesMoves.map((rm) => {
-        const newParent = deps.resolveParentPageId(rm.newPath, "current");
-        const oldParent = deps.resolveParentPageId(rm.oldPath, "prev");
-        const newTitle = deps.metaAt(rm.newPath, "current")?.title;
-        const oldTitle = deps.metaAt(rm.oldPath, "prev")?.title;
-        const out = {
-            pageId: rm.pageId,
-            oldPath: rm.oldPath,
-            newPath: rm.newPath,
-        };
-        // A reparent: the new path's resolved parent page differs from the old's.
-        if (newParent !== oldParent) {
-            out.move = { parentPageId: newParent };
-        }
-        // A title edit: only when there is a real, non-empty new title that changed.
-        if (typeof newTitle === "string" &&
-            newTitle.length > 0 &&
-            newTitle !== oldTitle) {
-            out.rename = { title: newTitle };
-        }
-        // Neither changed -> a purely LOCAL file-path rename; do NOT call Docmost.
-        if (!out.move && !out.rename) {
-            out.noop = true;
-        }
-        return out;
-    });
-}
-/**
- * PURE push planner (SPEC §4/§6/§8). Classifies each diff row into a Docmost
- * action by `pageId` identity, with NO IO (the `metaAt` resolver is injected).
- *
- * Classification rules:
- *   - `A` (added):
- *       - current meta HAS a pageId  -> UPDATE (a restored/copied file whose
- *         page already exists; we push its content rather than create a dup).
- *       - current meta has NO pageId but HAS a non-empty spaceId -> CREATE (a
- *         brand-new local file; the page does not exist in Docmost yet).
- *       - current meta has NO pageId and NO usable spaceId -> SKIP with reason
- *         `create-without-spaceId`: Docmost `create_page` REQUIRES a spaceId
- *         (§16), and a new local file may carry only partial human meta. We
- *         refuse to create rather than guess a space (SPEC §8 guard spirit).
- *   - `M` (modified): current meta has a pageId -> UPDATE content. (If a modified
- *       file somehow lost its pageId it is skipped — there is nothing to target.)
- *   - `D` (deleted): recover the pageId from the PRE-IMAGE meta (`metaAt(path,
- *       'prev')`) -> DELETE. If no pageId can be recovered, SKIP with a reason
- *       (untracked-file guard, SPEC §8: never delete an untracked page).
- *   - `R` (renamed/moved): same pageId (from current meta), path changed ->
- *       RENAME/MOVE. Resolution of move-vs-rename + the new parentPageId is
- *       DEFERRED to the next increment; here we only record oldPath/newPath/
- *       pageId. If the renamed file has no recoverable pageId it is SKIPPED.
- *       (`C` copy is treated the same as `R` for recording purposes.)
- */
-export function computePushActions(input) {
-    const { metaAt, currentPageIds } = input;
-    // PAGE-FILE FILTER (design §"Адопция"): only `.md` files OUTSIDE any dot-folder
-    // are Docmost pages. `.obsidian/*`, attachments, and other non-page files are
-    // committed to the vault (no `.gitignore`) and so appear in the diff, but they
-    // are NEVER pages — Obsidian owns them. Without this filter every ADDED such
-    // file would be mis-classified as a CREATE (nativeMeta always supplies a
-    // spaceId, so the old `create-without-spaceId` skip no longer screens them),
-    // creating junk pages in Docmost and corrupting the file with a `gitmost_id`
-    // frontmatter. Filter BEFORE any classification so non-page A/M/D/R are ignored.
-    const changes = input.changes.filter((c) => isPageFile(c.path));
-    const actions = {
-        creates: [],
-        updates: [],
-        deletes: [],
-        renamesMoves: [],
-        skipped: [],
-    };
-    // GHOST-MOVE coalescing (⭐ data-loss guard). git's rename detection (`-M`)
-    // can miss a move when the two files are too dissimilar — which is exactly the
-    // case for the tiny meta-only files a layout RESHUFFLE produces (e.g.
-    // several untitled pages sharing the `_` fallback name; retitling one frees the
-    // bare `_` and another page's file relocates `_ ~slug.md` -> `_.md`). git then
-    // reports the move as a DELETE of the old path + an ADD of the new one. Taken
-    // literally that soft-deletes a page that merely MOVED — a live page vanishing
-    // into Trash. Identity is the pageId, not git's heuristic: a pageId that is
-    // BOTH deleted (pre-image) and added (current) is one page that relocated, so
-    // we classify it as a rename/move and NEVER as a delete.
-    // A pageId can land at its new path two ways: as an ADD (the path was free) or
-    // as a MODIFY (the path was occupied by ANOTHER page that left — the reshuffle
-    // case, where `_.md`'s occupant changes pageId). Both are "the page survives at
-    // a new path", so the surviving side is the CURRENT-meta pageId of A *and* M.
-    const deletedPath = new Map();
-    const survivingPath = new Map();
-    for (const change of changes) {
-        if (change.status === "D") {
-            const pid = metaAt(change.path, "prev")?.pageId;
-            if (pid)
-                deletedPath.set(pid, change.path);
-        }
-        else if (change.status === "A" || change.status === "M") {
-            const pid = metaAt(change.path, "current")?.pageId;
-            if (pid)
-                survivingPath.set(pid, change.path);
-        }
-    }
-    const ghostMove = new Map();
-    for (const [pid, oldPath] of deletedPath) {
-        const newPath = survivingPath.get(pid);
-        if (newPath && newPath !== oldPath) {
-            ghostMove.set(pid, { oldPath, newPath });
-        }
-    }
-    for (const change of changes) {
-        switch (change.status) {
-            case "A": {
-                const meta = metaAt(change.path, "current");
-                const pageId = meta?.pageId;
-                if (pageId && ghostMove.has(pageId)) {
-                    // Half of a git-undetected move (a matching DELETE exists): record it
-                    // as a rename/move (like a real `R`), NOT an update — the `D` side is
-                    // suppressed so the page is never soft-deleted.
-                    actions.renamesMoves.push({
-                        pageId,
-                        oldPath: ghostMove.get(pageId).oldPath,
-                        newPath: change.path,
-                    });
-                }
-                else if (pageId) {
-                    // Added but already carries a pageId (restored/copied file): the page
-                    // exists in Docmost, so push content as an UPDATE — never a duplicate.
-                    actions.updates.push({ pageId, path: change.path });
-                }
-                else if (meta?.spaceId) {
-                    // Brand-new local file with a target space -> create the page, then
-                    // write the assigned pageId back into its meta (in `applyPushActions`).
-                    // `meta.spaceId` is truthy here, so empty-string is also rejected.
-                    actions.creates.push({ path: change.path });
-                }
-                else {
-                    // A create needs a spaceId (Docmost `create_page` requires it, §16). A
-                    // new file with partial meta and no usable spaceId is SKIPPED rather
-                    // than created into a guessed space (SPEC §8 guard spirit).
-                    actions.skipped.push({
-                        path: change.path,
-                        status: "A",
-                        reason: "create-without-spaceId",
-                    });
-                }
-                break;
-            }
-            case "M": {
-                const meta = metaAt(change.path, "current");
-                const pageId = meta?.pageId;
-                if (pageId && ghostMove.has(pageId)) {
-                    // This path's occupant changed pageId: the previous page left and THIS
-                    // page relocated here (a reshuffle). Its old file was DELETED elsewhere
-                    // — coalesce into a rename/move so the page is never trashed.
-                    actions.renamesMoves.push({
-                        pageId,
-                        oldPath: ghostMove.get(pageId).oldPath,
-                        newPath: change.path,
-                    });
-                }
-                else if (pageId) {
-                    actions.updates.push({ pageId, path: change.path });
-                }
-                else {
-                    // A modified file with no pageId has no Docmost target to update.
-                    actions.skipped.push({
-                        path: change.path,
-                        status: "M",
-                        reason: "modified file has no pageId in meta",
-                    });
-                }
-                break;
-            }
-            case "D": {
-                // The file is gone from `main`; recover its pageId from the PRE-IMAGE
-                // (the version last pushed to Docmost) so we delete the RIGHT page.
-                const prevMeta = metaAt(change.path, "prev");
-                const pageId = prevMeta?.pageId;
-                if (pageId && ghostMove.has(pageId)) {
-                    // The same pageId was re-ADDED at a new path: this is a git-undetected
-                    // MOVE, handled by the `A` branch above. Suppress the delete so a moved
-                    // page is never trashed (⭐ data-loss guard).
-                    actions.skipped.push({
-                        path: change.path,
-                        status: "D",
-                        reason: "ghost-move (re-added at a new path) — not a deletion",
-                    });
-                }
-                else if (pageId && currentPageIds?.has(pageId)) {
-                    // The pageId still EXISTS elsewhere in the current tree: the file moved
-                    // (a layout reshuffle whose matching add was in an earlier cycle, so it
-                    // is not in this diff). A live page must never be trashed because its
-                    // FILENAME changed — identity is the pageId (⭐ data-loss guard).
-                    actions.skipped.push({
-                        path: change.path,
-                        status: "D",
-                        reason: "pageId still present in the tree (moved) — not a deletion",
-                    });
-                }
-                else if (pageId) {
-                    actions.deletes.push({ pageId });
-                }
-                else {
-                    // Untracked-file guard (SPEC §8): a file with no recoverable pageId was
-                    // never a Docmost page — do NOT translate its removal into a delete.
-                    actions.skipped.push({
-                        path: change.path,
-                        status: "D",
-                        reason: "deleted file has no recoverable pageId (pre-image meta)",
-                    });
-                }
-                break;
-            }
-            case "R":
-            case "C": {
-                // Same page, new path. Identity comes from the CURRENT (post-rename) meta
-                // since the file still exists. RESOLUTION (move vs rename, parentPageId)
-                // is deferred — record oldPath/newPath/pageId only.
-                const meta = metaAt(change.path, "current");
-                const pageId = meta?.pageId;
-                const oldPath = change.oldPath ?? change.path;
-                if (pageId) {
-                    actions.renamesMoves.push({
-                        pageId,
-                        oldPath,
-                        newPath: change.path,
-                    });
-                }
-                else {
-                    actions.skipped.push({
-                        path: change.path,
-                        status: change.status,
-                        reason: "renamed/moved file has no pageId in meta",
-                    });
-                }
-                break;
-            }
-            default: {
-                // Unreachable for A/M/D/R/C; defensive for any future status.
-                actions.skipped.push({
-                    path: change.path,
-                    status: change.status,
-                    reason: `unhandled diff status ${change.status}`,
-                });
-            }
-        }
-    }
-    return actions;
-}
-// --- thin apply (create/update/delete), fakes-only in this increment ---------
-/** The marker the push direction advances after a successful push (SPEC §5/§6). */
-export const LAST_PUSHED_REF = "refs/docmost/last-pushed";
-/**
- * The mirror branch fast-forwarded after a clean push (SPEC §5/§6 step 3). It
- * reflects "what Docmost currently contains"; advancing it to the pushed `main`
- * commit closes the loop so the next pull diffs empty for the pushed pages.
- */
-export const DOCMOST_BRANCH = "docmost";
-/**
- * THIN IO applier for the COMMON push cases (create/update/delete). Exercised
- * via FAKES only in this increment — there is no live wiring.
- *
- *   - UPDATE: read the file body, then `client.importPageMarkdown(pageId, body)`.
- *     This is the collab/Yjs write path (SPEC §2/§15.6) — NEVER a raw jsonb
- *     overwrite. The full self-contained markdown (meta + body) is sent as-is;
- *     `importPageMarkdown` parses the meta/body itself.
- *   - CREATE: derive title/spaceId/parentPageId from the file's current meta,
- *     `client.createPage(...)`, take the assigned pageId from the result, and
- *     write it BACK as the file's `gitmost_id` frontmatter (re-serialized via
- *     `serializePageFile`, body preserved) so the file becomes
- *     tracked. The write-back is recorded in `writtenBack` (a follow-up commit
- *     is needed — NEXT increment).
- *   - DELETE: `client.deletePage(pageId)` — soft-delete to Trash (SPEC §8).
- *   - RENAME/MOVE (push #3, SPEC §5/§6/§16): classify each `renamesMoves` entry
- *     with `classifyRenameMoves` (resolvers read the parent FOLDER's `.md` for
- *     the parent pageId — path-as-truth — and the meta for the title), then:
- *       - `move`   -> `client.movePage(pageId, parentPageId, position?)` (reparent;
- *         `position` is UNDEFINED for now — the client supplies a default),
- *       - `rename` -> `client.renamePage(pageId, title)` (title-only),
- *       - BOTH     -> move (reparent) THEN rename (title), in that order,
- *       - `noop`   -> NO client call; recorded in `noops` (a cosmetic local-only
- *         file-path rename: the page is its pageId, the path is local, SPEC §5).
- *
- * FAIL-SAFE / per-page isolation (SPEC §12 resumability). Each page's operation
- * is wrapped in its own try/catch: a single failing page is recorded in
- * `failures[]` (with its kind + pageId/path + error) and the batch CONTINUES —
- * one bad page must never block the rest. Crucially, the refs are advanced ONLY
- * when `failures.length === 0`: a PARTIAL push must NOT advance
- * `refs/docmost/last-pushed` or the `docmost` mirror, so a re-run retries the
- * whole batch cleanly (the already-applied pages are idempotent re-applies).
- *
- * LOOP-CLOSE (SPEC §6 step 3 / §10). After a fully-successful push, when a
- * `pushedCommit` is supplied:
- *   - advance `refs/docmost/last-pushed` to it (what of `main` is in Docmost), AND
- *   - fast-forward the `docmost` mirror branch to it via
- *     `git.fastForwardBranch('docmost', pushedCommit)` — so the mirror reflects
- *     what Docmost now contains and the NEXT pull diffs EMPTY for these pages
- *     (it does not re-pull our own write). The ff is REFUSED (not forced) if
- *     `docmost` is not an ancestor of the pushed commit; the result is surfaced
- *     in `docmostFastForward`. On ANY failure, NEITHER ref is advanced.
- *
- * LOOP-GUARD DATA (SPEC §10). For every page successfully updated/created the
- * result carries a `pushed` record `{ pageId, updatedAt?, bodyHash }` — the body
- * hash of what was pushed plus the write's `updatedAt` (when the client returned
- * one). A future pull-side poll-suppression consults this so it does not re-pull
- * our own write; producing it is in scope here, consuming it is deferred.
- *
- * @param pushedCommit The `main` commit just reflected into Docmost (SHA or
- *   commit-ish). When omitted, NEITHER ref is advanced (e.g. a dry plan).
- */
-export async function applyPushActions(deps, actions, pushedCommit) {
-    const { client, git } = deps;
-    let created = 0;
-    let updated = 0;
-    let deleted = 0;
-    let moved = 0;
-    let renamed = 0;
-    const writtenBack = [];
-    const pushed = [];
-    const failures = [];
-    const noops = [];
-    // 1. UPDATES — collab/Yjs write path (SPEC §2/§15.6), never a raw overwrite.
-    //    Each update is isolated: a thrown page is recorded and the batch goes on.
-    for (const u of actions.updates) {
-        try {
-            // Push the CLEAN body only (no `gitmost_id` frontmatter): the frontmatter
-            // is engine metadata, never page content. The server converts the markdown
-            // it receives verbatim, so stripping here keeps the id out of Docmost.
-            const body = parsePageFile(await deps.readFile(u.path)).body;
-            // The last-synced version of this file (pre-image) is the common ancestor
-            // for a 3-way merge against the live page, so concurrent human edits are
-            // not clobbered (review #5). Null when the file is new at last-pushed. Its
-            // body is stripped the SAME way so the merge compares body-to-body.
-            const baseFull = await deps.git.showFileAtRef(LAST_PUSHED_REF, u.path);
-            const baseMarkdown = baseFull === null ? null : parsePageFile(baseFull).body;
-            const result = await client.importPageMarkdown(u.pageId, body, baseMarkdown);
-            updated++;
-            // §10 loop-guard data: hash the BODY we pushed + capture `updatedAt`.
-            pushed.push({
-                pageId: u.pageId,
-                ...extractUpdatedAt(result),
-                bodyHash: bodyHash(body),
-            });
-        }
-        catch (err) {
-            failures.push({
-                kind: "update",
-                pageId: u.pageId,
-                path: u.path,
-                error: errMessage(err),
-            });
-        }
-    }
-    // 2. CREATES — create the page, then write the assigned pageId back to meta so
-    //    the file becomes tracked (SPEC §4 "записать присвоенный pageId обратно").
-    //    Isolated per page like updates.
-    for (const c of actions.creates) {
-        try {
-            const text = await deps.readFile(c.path);
-            const { body } = parsePageFile(text);
-            // Derive create args from the PATH (native-Obsidian, SPEC §5): title from
-            // the filename, parent from the enclosing folder's folder-note, space from
-            // the run (the vault's space). `parentPageId: null` -> created at ROOT.
-            const title = titleFromPath(c.path);
-            const parentPageId = (await resolveParentPageIdViaTree(deps, c.path, "current")) ?? undefined;
-            const result = await client.createPage(title, body, deps.spaceId, parentPageId);
-            // `createPage` returns `{ data: { id, ... }, success }`; the assigned
-            // pageId is at `result.data.id`.
-            const assignedPageId = result?.data?.id;
-            if (assignedPageId) {
-                // Write the assigned pageId back as the `gitmost_id` frontmatter, body
-                // preserved — the file becomes engine-tracked (SPEC §4).
-                const rewritten = serializePageFile(assignedPageId, body);
-                await deps.writeFile(c.path, rewritten);
-                writtenBack.push({ path: c.path, pageId: assignedPageId });
-                // §10 loop-guard data for the created page (hash the pushed BODY).
-                pushed.push({
-                    pageId: assignedPageId,
-                    ...extractUpdatedAt(result),
-                    bodyHash: bodyHash(body),
-                });
-            }
-            created++;
-        }
-        catch (err) {
-            failures.push({ kind: "create", path: c.path, error: errMessage(err) });
-        }
-    }
-    // 3. DELETES — soft-delete to Trash (SPEC §8), reversible. Isolated per page.
-    for (const d of actions.deletes) {
-        try {
-            await client.deletePage(d.pageId);
-            deleted++;
-        }
-        catch (err) {
-            failures.push({
-                kind: "delete",
-                pageId: d.pageId,
-                error: errMessage(err),
-            });
-        }
-    }
-    // 4. RENAME/MOVE (push #3, SPEC §5/§6/§16). Classify each entry against the
-    //    tree-backed resolvers (the NEW parent comes from the new path's enclosing
-    //    folder `.md`, the OLD parent from the old path's at last-pushed — PATH is
-    //    the truth, not stale `meta.parentPageId`; the title from the meta), then
-    //    apply only the real ops. Each page is isolated like the cases above: a
-    //    thrown op is recorded in `failures` and the batch continues. ORDER for a
-    //    page that needs both: reparent (move) FIRST, then retitle (rename).
-    if (actions.renamesMoves.length > 0) {
-        // The classifier is PURE over sync resolvers; the tree reads are async, so
-        // prefetch every (path, side) lookup it will make into plain tables first.
-        const parentTable = new Map();
-        const metaTable = new Map();
-        // A tree read (readFile / git.showFileAtRef) throwing must isolate THAT page
-        // into `failures`, NOT abort the whole batch (§12 resumability). The helpers
-        // already swallow their own errors, but this per-entry try/catch keeps the
-        // batch-isolation invariant holding regardless of future changes to them.
-        const prefetchFailed = new Set();
-        for (const rm of actions.renamesMoves) {
-            // newParent + newTitle from the CURRENT tree; oldParent + oldTitle from the
-            // last-pushed pre-image (`prev`). Keyed by `path|side` so duplicates fold.
-            try {
-                parentTable.set(`${rm.newPath}|current`, await resolveParentPageIdViaTree(deps, rm.newPath, "current"));
-                parentTable.set(`${rm.oldPath}|prev`, await resolveParentPageIdViaTree(deps, rm.oldPath, "prev"));
-                metaTable.set(`${rm.newPath}|current`, await metaAtViaTree(deps, rm.newPath, "current", deps.spaceId));
-                metaTable.set(`${rm.oldPath}|prev`, await metaAtViaTree(deps, rm.oldPath, "prev", deps.spaceId));
-            }
-            catch (err) {
-                prefetchFailed.add(rm.pageId);
-                failures.push({
-                    kind: "move",
-                    pageId: rm.pageId,
-                    path: rm.newPath,
-                    error: errMessage(err),
-                });
-            }
-        }
-        const classified = classifyRenameMoves(actions.renamesMoves.filter((rm) => !prefetchFailed.has(rm.pageId)), {
-            metaAt: (path, side) => metaTable.get(`${path}|${side}`) ?? null,
-            resolveParentPageId: (path, side) => parentTable.get(`${path}|${side}`) ?? null,
-        });
-        for (const c of classified) {
-            if (c.noop) {
-                // Cosmetic local-only file-path rename — no Docmost op (SPEC §5).
-                noops.push({
-                    pageId: c.pageId,
-                    oldPath: c.oldPath,
-                    newPath: c.newPath,
-                    reason: "path-only-rename",
-                });
-                continue;
-            }
-            // Track which op is in flight so a failure is attributed to the op that
-            // ACTUALLY threw: for a page needing both, a move that succeeds then a
-            // rename that throws must be recorded as `rename`, not `move`.
-            let failingKind = c.move ? "move" : "rename";
-            try {
-                // Reparent FIRST so the page is in its new tree position, THEN retitle.
-                if (c.move) {
-                    failingKind = "move";
-                    // TODO(next): compute a fractional-index position between siblings
-                    // (SPEC §16). `position` is UNDEFINED here; the client supplies a valid
-                    // default. Pass `parentPageId: null` for a move to the space ROOT.
-                    await client.movePage(c.pageId, c.move.parentPageId);
-                    moved++;
-                }
-                if (c.rename) {
-                    failingKind = "rename";
-                    await client.renamePage(c.pageId, c.rename.title);
-                    renamed++;
-                }
-            }
-            catch (err) {
-                // Isolate the failed page: the op that ACTUALLY threw is recorded so a
-                // re-run can retry. A move that threw before its rename leaves `rename`
-                // for the next run (idempotent re-apply); refs are NOT advanced (below).
-                failures.push({
-                    kind: failingKind,
-                    pageId: c.pageId,
-                    path: c.newPath,
-                    error: errMessage(err),
-                });
-            }
-        }
-    }
-    // 5. Advance the refs ONLY on a CLEAN push (no failures) AND when a pushed
-    //    commit is supplied. A partial push must advance NEITHER ref, so a re-run
-    //    retries the whole batch (SPEC §12). The loop-close (SPEC §6 step 3 / §10):
-    //    advance `refs/docmost/last-pushed` AND fast-forward the `docmost` mirror,
-    //    so Docmost's new content is mirrored and the next pull diffs empty.
-    let lastPushedAdvanced = false;
-    let docmostFastForward = null;
-    if (pushedCommit && failures.length === 0) {
-        await git.updateRef(LAST_PUSHED_REF, pushedCommit);
-        lastPushedAdvanced = true;
-        // Fast-forward the mirror (refused, not forced, on a non-fast-forward — the
-        // caller logs the reason). Surfaced in the result.
-        docmostFastForward = await git.fastForwardBranch(DOCMOST_BRANCH, pushedCommit);
-    }
-    return {
-        created,
-        updated,
-        deleted,
-        moved,
-        renamed,
-        writtenBack,
-        pushed,
-        failures,
-        noops,
-        skipped: actions.skipped,
-        lastPushedAdvanced,
-        docmostFastForward,
-    };
-}
-/** Stringify a thrown value into a stable error message. */
-function errMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-/**
- * SPEC §5 path-as-truth: the parent FOLDER's `.md` file for a vault-relative
- * (forward-slash) path. `buildVaultLayout` puts a page with children at
- * `<...>/Title.md` and nests its children under `<...>/Title/`, so for
- * `newPath = <dir>/Child.md` the parent page's file is `<dir>.md` (the enclosing
- * folder, one level up). A path with NO enclosing folder (`Child.md`, at the
- * space root) has no parent folder file -> `null` (the parent is ROOT).
- */
-export function parentFolderFile(path) {
-    const slash = path.lastIndexOf("/");
-    if (slash < 0)
-        return null; // root-level file: parent is ROOT.
-    const dir = path.slice(0, slash); // the enclosing folder
-    // The page that OWNS the enclosing folder is its folder-note `<dir>/<base>.md`.
-    const folderNote = `${dir}/${baseSegment(dir)}.md`;
-    if (path === folderNote) {
-        // This path IS its folder's folder-note, so its parent is ONE LEVEL UP: the
-        // folder-note of the grandparent folder (or ROOT at the top level).
-        const up = dir.lastIndexOf("/");
-        if (up < 0)
-            return null; // top-level folder -> parent is ROOT.
-        const grandDir = dir.slice(0, up);
-        return `${grandDir}/${baseSegment(grandDir)}.md`;
-    }
-    // A leaf (or a nested folder-note) sitting inside `dir`: its parent is `dir`'s
-    // folder-note.
-    return folderNote;
-}
-/**
- * Whether a vault path is a Docmost PAGE file (design §"Адопция"): a `.md` file
- * with NO dot-segment anywhere in its path. This excludes `.obsidian/` config,
- * `.trash/`, dotfiles (`.foo.md`), and every non-`.md` file (attachments, JSON,
- * …) — Obsidian owns those; they live in the vault but are never pages. Used to
- * screen the PUSH diff so non-page files are never created/updated/deleted in
- * Docmost (and never get a `gitmost_id` frontmatter written into them).
- */
-export function isPageFile(path) {
-    if (!path.endsWith(".md"))
-        return false;
-    return !path.split("/").some((seg) => seg.startsWith("."));
-}
-/** The last path segment of a forward-slash path (the folder/file base name). */
-function baseSegment(path) {
-    const slash = path.lastIndexOf("/");
-    return slash < 0 ? path : path.slice(slash + 1);
-}
-/**
- * The page TITLE derived from a vault path: the file's base name without the
- * `.md` extension. In the native-Obsidian layout the filename IS the title — for
- * a folder-note `<dir>/<base>.md` that base equals the folder name, so the same
- * rule yields the folder's title. Self-consistent across pull/push: a pulled
- * (possibly disambiguated) filename round-trips to the same title, so a stable
- * file never pushes a spurious rename.
- */
-function titleFromPath(path) {
-    const base = baseSegment(path);
-    return base.endsWith(".md") ? base.slice(0, -3) : base;
-}
-/**
- * Build the synthetic `DocmostMdMeta` the planner/classifier consume, from the
- * NATIVE format: `pageId` from the `gitmost_id` frontmatter, `title` from the
- * filename, `spaceId` from the run (the vault's space — every file belongs to
- * it). `parentPageId` is intentionally absent: tree position is resolved from the
- * PATH (`resolveParentPageId`), never from a stored field (SPEC §5).
- */
-function nativeMeta(text, path, spaceId) {
-    const { id } = parsePageFile(text);
-    const meta = { version: 1, title: titleFromPath(path), spaceId };
-    if (id)
-        meta.pageId = id;
-    return meta;
-}
-/**
- * Build the `resolveParentPageId(path, side)` resolver `classifyRenameMoves`
- * needs, reading the PARENT FOLDER's `.md` (SPEC §5 path-as-truth):
- *   - `current` -> `deps.readFile(<dir>.md)` (the live working tree),
- *   - `prev`    -> `git.showFileAtRef('refs/docmost/last-pushed', <dir>.md)` (the
- *     last-pushed pre-image),
- * then read its `gitmost_id` frontmatter and return that page's pageId. A root-level path
- * (no enclosing folder), a missing/unreadable parent file, or a parent file with
- * no parseable pageId all resolve to `null` (parent is ROOT / unknown ->
- * `parentPageId: null`, SPEC §16 "parentPageId: null -> в корень").
- *
- * The IO is async, so this returns an ASYNC resolver; the call sites prefetch the
- * parent pageIds (the classifier itself stays pure/sync over a plain table).
- */
-async function resolveParentPageIdViaTree(deps, path, side) {
-    const parentFile = parentFolderFile(path);
-    if (parentFile === null)
-        return null; // root-level: parent is ROOT.
-    let text;
-    try {
-        text =
-            side === "current"
-                ? await deps.readFile(parentFile)
-                : await deps.git.showFileAtRef(LAST_PUSHED_REF, parentFile);
-    }
-    catch {
-        // Parent folder file missing/unreadable at that side -> treat as ROOT.
-        return null;
-    }
-    if (text === null)
-        return null; // showFileAtRef returns null when absent.
-    // The parent page's identity is its `gitmost_id` frontmatter; folder position
-    // is irrelevant here, only the pageId.
-    return parsePageFile(text).id;
-}
-/**
- * Resolve the synthetic native meta at a side for the rename/move classifier (the
- * title — derived from the path — comes from here). Mirrors
- * `resolveParentPageIdViaTree`'s IO sides: `current` reads the working tree,
- * `prev` reads `refs/docmost/last-pushed`. Returns `null` only when the file is
- * missing/unreadable at that side (a real absence the classifier must see).
- */
-async function metaAtViaTree(deps, path, side, spaceId) {
-    let text;
-    try {
-        text =
-            side === "current"
-                ? await deps.readFile(path)
-                : await deps.git.showFileAtRef(LAST_PUSHED_REF, path);
-    }
-    catch {
-        return null;
-    }
-    if (text === null)
-        return null;
-    return nativeMeta(text, path, spaceId);
-}
-/**
- * Pull an `updatedAt` out of a create/update client result, if present. The
- * shape is `{ data: { updatedAt? }, ... }` (createPage) or a flatter object;
- * absent in the simple fakes, so the field is omitted rather than `undefined`.
- */
-function extractUpdatedAt(result) {
-    const r = result;
-    const raw = r?.data?.updatedAt ?? r?.updatedAt;
-    return typeof raw === "string" ? { updatedAt: raw } : {};
-}
-// --- runnable push orchestration (`runPush`) ---------------------------------
-//
-// `runPush` is the FS->Docmost twin of `pull.ts`'s `main`: it wires the VaultGit
-// diff/ref primitives + the PURE `computePushActions` planner + the THIN
-// `applyPushActions` applier into one runnable cycle. SAFE BY DEFAULT — the
-// engine's FIRST write path to Docmost defaults to DRY-RUN (plan only, NO
-// Docmost writes, NO ref advance); an explicit `--apply` is the ONLY path that
-// builds a client and mutates Docmost.
-//
-// Every external effect is injected (`PushDeps`) so the whole orchestration is
-// driven by FAKES in tests — no live Docmost, git, fs, or network.
-/**
- * The human ("local") git identity used for engine-made commits on `main` in the
- * push direction (SPEC §7.3). The provenance is carried by the trailer (below),
- * which the loop-guard keys on; the identity is for history readability only.
- * When the vault repo already has a configured `user.name`/`user.email`, git
- * uses that for the working-tree commit; this is the fallback the daemon stamps.
- */
-export const LOCAL_AUTHOR_NAME = "Local";
-export const LOCAL_AUTHOR_EMAIL = "local@local";
-/** The provenance trailer marking a `main`-side (human/local) commit (SPEC §7.3). */
-export const LOCAL_SOURCE_TRAILER = "Docmost-Sync-Source: local";
-/**
- * Run one FS->Docmost push cycle (SPEC §6 "ФС → Docmost"), DRY-RUN BY DEFAULT.
- *
- * Steps (mirrors `pull.ts`):
- *   1. Preflight git: `assertGitAvailable` + `ensureRepo`; ABORT (clear message +
- *      non-zero-ish result) if a merge is in progress — never push on top of an
- *      unresolved conflict (SPEC §9/§12). Conflict markers must NEVER reach
- *      Docmost (SPEC §9).
- *   2. Checkout `main` (the human-facing branch the push reads from).
- *   3. Commit the human's pending working-tree changes on `main` with the
- *      `local` provenance trailer (SPEC §7.3). A no-op when nothing changed.
- *   4. Pick the diff BASE: `refs/docmost/last-pushed` if it resolves, else the
- *      `docmost` mirror branch (what Docmost currently has). Resolve `main`.
- *   5. `diffNameStatus(base, main)` -> changes; build the `metaAt(path, side)`
- *      resolver (current = working tree, prev = `git show <base>:<path>`); run
- *      the PURE `computePushActions`.
- *   6. DRY-RUN (default): LOG the full plan and RETURN — NO client, NO Docmost
- *      calls, NO ref advance.
- *   7. `--apply`: build the client, run `applyPushActions(..., pushedCommit=main)`,
- *      then (a) if any pageIds were written back (creates), commit them on `main`
- *      with the `local` trailer and RE-advance `refs/docmost/last-pushed` to the
- *      new commit so the recorded pageIds are persisted in what Docmost mirrors;
- *      (b) ESCALATE a divergent-`docmost` ff refusal (SPEC §5) with a prominent
- *      WARNING and a non-zero-ish flag. Then log a one-line summary.
- */
-export async function runPush(deps, opts) {
-    const { git, settings, log } = deps;
-    const dryRun = opts.dryRun;
-    // 1. Preflight git. Fail fast (actionable message via main().catch) if the git
-    //    binary is missing — the vault state store relies on it.
-    await git.assertGitAvailable();
-    await git.ensureRepo();
-    // 1b. Refuse to push on top of an unresolved merge (SPEC §9/§12). A previous
-    //     conflicting pull leaves the vault mid-merge; pushing now could leak
-    //     conflict markers into Docmost (SPEC §9, the cardinal invariant). Detect
-    //     it BEFORE any checkout/diff and stop with a clear, actionable message so
-    //     re-runs converge once the human resolves (or aborts) the merge.
-    if (await git.isMergeInProgress()) {
-        log(`push: vault has an unresolved merge at ${settings.vaultPath} — resolve ` +
-            `it (or 'git merge --abort') and re-run. Nothing was pushed to Docmost ` +
-            `(conflict markers must never reach Docmost, SPEC §9).`);
-        return { mode: dryRun ? "dry-run" : "apply", aborted: "merge-in-progress" };
-    }
-    // 2. Work on `main` — the human-facing branch the push diffs FROM.
-    await git.checkout(DEFAULT_BRANCH);
-    // 3. Commit the human's pending working-tree changes on `main` with the `local`
-    //    provenance trailer (SPEC §7.3). A no-op commit when nothing changed is
-    //    fine (`commit` returns false). The loop-guard keys on the trailer.
-    //    Even on a "plan only" dry-run this commits the working tree (it is the
-    //    only way to diff `base..main`, acceptable §6.1 behavior) — so make that
-    //    LOCAL git mutation VISIBLE, never silent: a created commit is local-only
-    //    and nothing is sent to Docmost.
-    await git.stageAll();
-    const committedWorkingTree = await git.commit("local: working-tree changes", {
-        authorName: LOCAL_AUTHOR_NAME,
-        authorEmail: LOCAL_AUTHOR_EMAIL,
-        trailers: [LOCAL_SOURCE_TRAILER],
-    });
-    if (committedWorkingTree) {
-        const sha = await git.revParse(DEFAULT_BRANCH);
-        log(`push: committed local working-tree changes on main` +
-            (sha ? ` as ${sha.slice(0, 8)}` : "") +
-            ` (local git only — nothing sent to Docmost).`);
-    }
-    else {
-        log("push: working tree clean (no local changes to push).");
-    }
-    // 4. Pick the diff BASE (SPEC §5/§6): `refs/docmost/last-pushed` if it resolves
-    //    (the marker of what `main` is already in Docmost), else fall back to the
-    //    `docmost` mirror branch (the mirror of what Docmost currently has) — which
-    //    is what exists before the first push ever advanced last-pushed.
-    let base;
-    const lastPushedSha = await git.readRef(LAST_PUSHED_REF);
-    if (lastPushedSha) {
-        base = { ref: LAST_PUSHED_REF, source: "last-pushed", sha: lastPushedSha };
-    }
-    else {
-        base = {
-            ref: DOCMOST_BRANCH,
-            source: "docmost",
-            sha: await git.revParse(DOCMOST_BRANCH),
-        };
-    }
-    const pushedCommit = await git.revParse(DEFAULT_BRANCH);
-    if (!pushedCommit) {
-        // `main` has no commit — `ensureRepo` always makes an initial one, so this is
-        // defensive. Nothing to diff.
-        log("push: `main` has no commit to push — nothing to do.");
-        return { mode: dryRun ? "dry-run" : "apply", base };
-    }
-    // 5. Diff the base against `main` and build the `metaAt` resolver (PURE planner
-    //    input). `current` reads the live working tree; `prev` reads the base ref's
-    //    pre-image via `git show <base>:<path>` (so a DELETE recovers its pageId).
-    const changes = await git.diffNameStatus(base.ref, DEFAULT_BRANCH);
-    // Synchronous resolver over PREFETCHED meta tables: `computePushActions` is
-    // PURE/sync, but the file/ref reads are async — so we prefetch every (path,
-    // side) the diff will ask for into a table first, then resolve from it.
-    const metaTable = new Map();
-    for (const change of changes) {
-        // `current`: A/M/R/C still have the file on `main`. `prev`: D needs the
-        // pre-image; R/C also benefit (old title). Prefetch both sides per path.
-        const currentPath = change.path;
-        const prevPath = change.oldPath ?? change.path;
-        if (!metaTable.has(`${currentPath}|current`)) {
-            metaTable.set(`${currentPath}|current`, await readMetaCurrent(deps, currentPath, settings.docmostSpaceId));
-        }
-        if (!metaTable.has(`${prevPath}|prev`)) {
-            metaTable.set(`${prevPath}|prev`, await readMetaPrev(deps, base.ref, prevPath, settings.docmostSpaceId));
-        }
-    }
-    const metaAt = (path, side) => metaTable.get(`${path}|${side}`) ?? null;
-    // The set of pageIds that STILL EXIST somewhere in the current `main` tree.
-    // Identity is the pageId, NOT the filename: a file vanishing from one path
-    // while the SAME pageId lives at another path is a MOVE (often a layout
-    // reshuffle of `_`-fallback names, whose two halves can even land in separate
-    // cycles), never a deletion. Built only when the diff contains deletes — the
-    // guard's whole job is to stop a phantom delete from trashing a live page.
-    let currentPageIds;
-    if (changes.some((c) => c.status === "D")) {
-        currentPageIds = new Set();
-        for (const relPath of await git.listTrackedFiles("*.md")) {
-            const pid = (await readMetaCurrent(deps, relPath, settings.docmostSpaceId))
-                ?.pageId;
-            if (pid)
-                currentPageIds.add(pid);
-        }
-    }
-    const actions = computePushActions({ changes, metaAt, currentPageIds });
-    const planned = {
-        creates: actions.creates.length,
-        updates: actions.updates.length,
-        deletes: actions.deletes.length,
-        renamesMoves: actions.renamesMoves.length,
-        skipped: actions.skipped.length,
-    };
-    // 6. DRY-RUN (default): log the full plan and RETURN — build NO client, make
-    //    ZERO Docmost calls, advance NO refs. This is the SAFE default.
-    logPlan(log, base, pushedCommit, actions, planned, dryRun);
-    if (dryRun) {
-        return { mode: "dry-run", base, pushedCommit, planned };
-    }
-    // 7. --apply: build the REAL client and execute. This is the ONLY write path.
-    const client = deps.makeClient(settings);
-    const applied = await applyPushActions({
-        client,
-        // Pass the WHOLE `git` object (it satisfies the applier's
-        // `Pick<VaultGit, ...>` deps surface). Passing bare method references
-        // (`git.updateRef`, …) would lose their `this` binding, so on a REAL
-        // `VaultGit` they would throw `this.runRaw is not a function`. Hand over
-        // the object so the methods keep their receiver — exactly as `pull.ts`
-        // does for `applyPullActions`.
-        git,
-        readFile: deps.readFile,
-        writeFile: deps.writeFile,
-        spaceId: settings.docmostSpaceId,
-    }, actions, pushedCommit);
-    // 7a. Persist freshly-assigned pageIds (creates) back into git. `applyPushActions`
-    //     rewrote those files on disk; commit them on `main` with the `local` trailer
-    //     so the new pageIds are recorded, then RE-advance `refs/docmost/last-pushed`
-    //     to the new commit so what Docmost mirrors and what last-pushed points at
-    //     stay in lock-step (the write-back commit is part of `main` now).
-    // Track a divergent-`docmost` mirror across BOTH ff sites (the applier's main
-    // push ff in 7b, and the write-back ff here). A divergent mirror is a §5
-    // invariant breach in EITHER branch and must escalate identically (exit 1).
-    let divergentDocmost = false;
-    if (applied.writtenBack.length > 0) {
-        await git.stageAll();
-        const recorded = await git.commit("local: record created pageIds", {
-            authorName: LOCAL_AUTHOR_NAME,
-            authorEmail: LOCAL_AUTHOR_EMAIL,
-            trailers: [LOCAL_SOURCE_TRAILER],
-        });
-        if (recorded) {
-            const newCommit = await git.revParse(DEFAULT_BRANCH);
-            // Only re-advance when the original push was CLEAN (last-pushed was already
-            // advanced by the applier); a partial push left the refs untouched and a
-            // re-run retries the whole batch, so we must not move them either.
-            if (newCommit && applied.lastPushedAdvanced) {
-                await git.updateRef(LAST_PUSHED_REF, newCommit);
-                const ff = await git.fastForwardBranch(DOCMOST_BRANCH, newCommit);
-                if (!ff.ok) {
-                    // SYMMETRIC with the main escalation (7b): a divergent mirror in the
-                    // write-back branch is the SAME §5 invariant breach and must escalate
-                    // (exit 1), not just log a soft warning.
-                    divergentDocmost = true;
-                    log(`push: WARNING — the 'docmost' mirror branch DIVERGED and was NOT ` +
-                        `fast-forwarded to the pageId write-back commit ` +
-                        `(${ff.reason ?? "not-fast-forward"}). The §5 invariant ('docmost' ` +
-                        `mirrors what Docmost contains) is broken: reconcile 'docmost' ` +
-                        `against the live Docmost tree before the next cycle.`);
-                }
-            }
-        }
-    }
-    // 7b. ESCALATE a divergent-`docmost` fast-forward refusal (SPEC §5 invariant
-    //     broken). The applier already refused to clobber a divergent mirror; make
-    //     it LOUD (not silent) so the operator notices, and fold it into the exit.
-    if (applied.docmostFastForward && !applied.docmostFastForward.ok) {
-        divergentDocmost = true;
-        log(`push: WARNING — the 'docmost' mirror branch DIVERGED and was NOT ` +
-            `fast-forwarded (${applied.docmostFastForward.reason ?? "not-fast-forward"}). ` +
-            `The §5 invariant ('docmost' mirrors what Docmost contains) is broken: ` +
-            `reconcile 'docmost' against the live Docmost tree before the next cycle.`);
-    }
-    // 7c. One-line summary (mirrors pull.ts's summary line).
-    log(`push complete: ${applied.created} created, ${applied.updated} updated, ` +
-        `${applied.deleted} deleted, ${applied.moved} moved, ${applied.renamed} ` +
-        `renamed, ${applied.noops.length} no-op(s), ${applied.skipped.length} ` +
-        `skipped, ${applied.failures.length} failure(s)` +
-        (divergentDocmost ? " [DIVERGENT docmost mirror]" : ""));
-    return {
-        mode: "apply",
-        base,
-        pushedCommit,
-        planned,
-        applied,
-        divergentDocmost,
-        failures: applied.failures,
-    };
-}
-/** Synthetic native meta from the live working tree (`current` side). */
-async function readMetaCurrent(deps, path, spaceId) {
-    let text;
-    try {
-        text = await deps.readFile(path);
-    }
-    catch {
-        return null; // absent on disk (e.g. a D row's path) -> no current meta.
-    }
-    return nativeMeta(text, path, spaceId);
-}
-/** Synthetic native meta from the base ref's pre-image (`prev` side). */
-async function readMetaPrev(deps, baseRef, path, spaceId) {
-    let text;
-    try {
-        text = await deps.git.showFileAtRef(baseRef, path);
-    }
-    catch {
-        return null;
-    }
-    if (text === null)
-        return null; // path absent at the base ref.
-    return nativeMeta(text, path, spaceId);
-}
-/** Emit the full plan (counts + per-item) to the injected logger. */
-function logPlan(log, base, pushedCommit, actions, planned, dryRun) {
-    log(`push plan (${dryRun ? "DRY-RUN — no Docmost writes" : "APPLY"}): base=` +
-        `${base.ref} (${base.source}${base.sha ? ` ${base.sha.slice(0, 8)}` : ""}) ` +
-        `-> main ${pushedCommit.slice(0, 8)}`);
-    log(`push plan counts: ${planned.creates} create, ${planned.updates} update, ` +
-        `${planned.deletes} delete, ${planned.renamesMoves} rename/move, ` +
-        `${planned.skipped} skipped`);
-    for (const c of actions.creates)
-        log(`  create: ${c.path}`);
-    for (const u of actions.updates)
-        log(`  update: ${u.pageId} (${u.path})`);
-    for (const d of actions.deletes)
-        log(`  delete: ${d.pageId}`);
-    for (const rm of actions.renamesMoves)
-        log(`  rename/move: ${rm.oldPath} -> ${rm.newPath} (${rm.pageId})`);
-    for (const s of actions.skipped)
-        log(`  skipped [${s.status}] ${s.path}: ${s.reason}`);
-}
-/**
- * Parse the `push` CLI flags. SAFE BY DEFAULT: without `--apply` the run is a
- * DRY-RUN (plan only). Exported so the flag handling is unit-testable.
- */
-export function parseArgs(argv) {
-    return { apply: argv.includes("--apply") };
-}

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

@@ -1,126 +0,0 @@
-/**
- * Pure reconciliation planner (SPEC §5/§6/§8).
- *
- * Given the desired live set of files (computed from the current Docmost tree)
- * and the set of files currently tracked in the vault, compute what to write,
- * what to move (old path to remove), and what to delete. Identity is `pageId`
- * (the stable file<->page anchor, SPEC §4): a page that keeps its pageId but
- * changes relPath is a MOVE, not delete+add; a tracked pageId that is gone from
- * the live tree is a DELETE.
- *
- * This module is intentionally PURE (no IO, no git) so the whole plan is
- * unit-testable. The actual file writing / git operations happen in pull.ts.
- */
-/** A page that SHOULD exist in the vault at a given path. */
-export interface LiveEntry {
-    pageId: string;
-    /** Vault-relative path (forward-slash), e.g. `Space/Parent/Child.md`. */
-    relPath: string;
-}
-/** A page currently tracked in the vault (pageId parsed from its meta). */
-export interface ExistingEntry {
-    pageId: string;
-    /** Vault-relative path (forward-slash) of the tracked file. */
-    relPath: string;
-}
-/** A page to (re)write at its destination path. */
-export interface WriteEntry {
-    pageId: string;
-    relPath: string;
-}
-/** A page that moved: written at its NEW relPath, with the OLD path removed. */
-export interface MovedEntry {
-    pageId: string;
-    fromRelPath: string;
-    toRelPath: string;
-    /**
-     * Whether the old path (`fromRelPath`) is SAFE to remove. False when another
-     * live page will (re)write that exact path (path reuse): removing it would
-     * destroy real data, so the caller must skip the removal. The move itself is
-     * still recorded (the new path is written regardless).
-     */
-    removeOldPath: boolean;
-}
-/** The full reconciliation plan. */
-export interface ReconciliationPlan {
-    /**
-     * Pages present in `live` -> (re)write at their relPath. This naturally
-     * covers add, content-update (same path) AND move (same pageId, new path),
-     * since every live page is (re)written regardless of whether it existed.
-     */
-    toWrite: WriteEntry[];
-    /**
-     * Vault-relative paths to delete because their tracked pageId is ABSENT from
-     * `live` (page removed/trashed). This set is ONLY absence-based deletions —
-     * the OLD paths of moved pages are NOT here (they live in `moved` and are
-     * applied separately by the caller). Keeping the two apart lets pull.ts gate
-     * absence deletions behind the incomplete-fetch suppression + mass-delete
-     * guard (SPEC §8) while still applying real moves.
-     */
-    toDelete: string[];
-    /**
-     * Tracked pages whose relPath changed. The caller writes the page at
-     * `toRelPath`, then removes `fromRelPath` — but ONLY after the new-path write
-     * succeeded. The old path is NOT in `toDelete`.
-     */
-    moved: MovedEntry[];
-}
-/**
- * Compute the reconciliation plan.
- *
- * Rules:
- *   - Every `live` page is written at its relPath (covers add + update + move).
- *   - A tracked pageId present in `live` whose relPath changed is `moved`; its
- *     OLD relPath goes into `moved` ONLY (the caller removes it after the new
- *     path is written) and is NEVER added to `toDelete`.
- *   - A tracked pageId NOT present in `live` is an ABSENCE delete; its relPath
- *     is added to `toDelete`.
- *
- * Notes:
- *   - Safety filter (no data loss): no path that is a live TARGET path of any
- *     page is ever deleted/removed (a write owns it). This applies to BOTH the
- *     absence `toDelete` set AND a moved page's old-path removal — if a moved
- *     page's OLD path is reused by ANOTHER live page, the move records no old
- *     path to remove, because that path will be (re)written.
- *   - `existing` may legitimately contain duplicate pageIds (two stray files
- *     carrying the same meta pageId); each such file that is not the live target
- *     path is removed (as an absence/move) so the vault converges to exactly the
- *     live set.
- */
-export declare function planReconciliation(live: LiveEntry[], existing: ExistingEntry[]): ReconciliationPlan;
-/**
- * Below this many tracked files the mass-delete fraction guard is not applied
- * (a tiny vault where deleting "most" files is normal, e.g. 1-of-2).
- */
-export declare const MASS_DELETE_MIN_EXISTING = 4;
-/** Fraction of tracked files above which a delete plan is a suspected wipe. */
-export declare const MASS_DELETE_FRACTION = 0.5;
-/** Why absence-based deletions were (or were not) applied this cycle. */
-export type DeletionDecision = {
-    apply: true;
-} | {
-    apply: false;
-    reason: "incomplete-fetch" | "empty-live" | "mass-delete";
-};
-/**
- * Pure decision: should the ABSENCE-based deletions (`plan.toDelete`) be applied
- * this cycle? Encapsulates the SPEC §8 safety invariants so they are unit-
- * testable without live creds or git:
- *
- *   - `treeComplete === false` (a partial Docmost tree fetch) -> SUPPRESS. A page
- *     missing from a partial tree is NOT proof of deletion (SPEC §8); we must not
- *     delete merely-absent files this cycle. (Writes/updates/moves still happen.)
- *   - The live fetch returned 0 pages while files are tracked -> SUPPRESS
- *     (almost always a failed fetch, never a real "delete everything").
- *   - The plan would delete more than `MASS_DELETE_FRACTION` of a non-trivial
- *     vault -> SUPPRESS as a mass-deletion guard (defense in depth).
- *
- * Moves are NOT governed by this decision: a moved page IS present in `live`, so
- * its old-path removal is real (handled by the caller separately).
- */
-export declare function decideAbsenceDeletions(args: {
-    treeComplete: boolean;
-    liveCount: number;
-    existingCount: number;
-    deleteCount: number;
-}): DeletionDecision;

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

@@ -1,117 +0,0 @@
-/**
- * Pure reconciliation planner (SPEC §5/§6/§8).
- *
- * Given the desired live set of files (computed from the current Docmost tree)
- * and the set of files currently tracked in the vault, compute what to write,
- * what to move (old path to remove), and what to delete. Identity is `pageId`
- * (the stable file<->page anchor, SPEC §4): a page that keeps its pageId but
- * changes relPath is a MOVE, not delete+add; a tracked pageId that is gone from
- * the live tree is a DELETE.
- *
- * This module is intentionally PURE (no IO, no git) so the whole plan is
- * unit-testable. The actual file writing / git operations happen in pull.ts.
- */
-/**
- * Compute the reconciliation plan.
- *
- * Rules:
- *   - Every `live` page is written at its relPath (covers add + update + move).
- *   - A tracked pageId present in `live` whose relPath changed is `moved`; its
- *     OLD relPath goes into `moved` ONLY (the caller removes it after the new
- *     path is written) and is NEVER added to `toDelete`.
- *   - A tracked pageId NOT present in `live` is an ABSENCE delete; its relPath
- *     is added to `toDelete`.
- *
- * Notes:
- *   - Safety filter (no data loss): no path that is a live TARGET path of any
- *     page is ever deleted/removed (a write owns it). This applies to BOTH the
- *     absence `toDelete` set AND a moved page's old-path removal — if a moved
- *     page's OLD path is reused by ANOTHER live page, the move records no old
- *     path to remove, because that path will be (re)written.
- *   - `existing` may legitimately contain duplicate pageIds (two stray files
- *     carrying the same meta pageId); each such file that is not the live target
- *     path is removed (as an absence/move) so the vault converges to exactly the
- *     live set.
- */
-export function planReconciliation(live, existing) {
-    // Desired path for each live pageId.
-    const liveByPageId = new Map();
-    // Set of all paths that WILL be written (never delete/remove one of these).
-    const liveTargetPaths = new Set();
-    for (const e of live) {
-        liveByPageId.set(e.pageId, e.relPath);
-        liveTargetPaths.add(e.relPath);
-    }
-    const toWrite = live.map((e) => ({
-        pageId: e.pageId,
-        relPath: e.relPath,
-    }));
-    const moved = [];
-    // Absence-based deletions ONLY (tracked pageId absent from `live`). Use a Set
-    // so the same path coming from multiple existing rows is queued only once.
-    const toDeleteSet = new Set();
-    for (const ex of existing) {
-        const liveRel = liveByPageId.get(ex.pageId);
-        if (liveRel === undefined) {
-            // Tracked page is gone from the live tree -> absence delete.
-            // Never queue a path a live page will (re)write (path reuse -> no loss).
-            if (!liveTargetPaths.has(ex.relPath))
-                toDeleteSet.add(ex.relPath);
-            continue;
-        }
-        if (liveRel !== ex.relPath) {
-            // Same pageId, different path -> a MOVE. Record it so the caller can write
-            // the new path first, then remove the old one. If the old path is itself a
-            // live target (reused by another page), it must NOT be removed — the write
-            // owns it — so flag `removeOldPath: false` (move still recorded).
-            moved.push({
-                pageId: ex.pageId,
-                fromRelPath: ex.relPath,
-                toRelPath: liveRel,
-                removeOldPath: !liveTargetPaths.has(ex.relPath),
-            });
-        }
-        // liveRel === ex.relPath -> content-update in place; nothing extra to do
-        // (the write above re-emits the file; identical bytes => git no-op).
-    }
-    const toDelete = [...toDeleteSet];
-    return { toWrite, toDelete, moved };
-}
-/**
- * Below this many tracked files the mass-delete fraction guard is not applied
- * (a tiny vault where deleting "most" files is normal, e.g. 1-of-2).
- */
-export const MASS_DELETE_MIN_EXISTING = 4;
-/** Fraction of tracked files above which a delete plan is a suspected wipe. */
-export const MASS_DELETE_FRACTION = 0.5;
-/**
- * Pure decision: should the ABSENCE-based deletions (`plan.toDelete`) be applied
- * this cycle? Encapsulates the SPEC §8 safety invariants so they are unit-
- * testable without live creds or git:
- *
- *   - `treeComplete === false` (a partial Docmost tree fetch) -> SUPPRESS. A page
- *     missing from a partial tree is NOT proof of deletion (SPEC §8); we must not
- *     delete merely-absent files this cycle. (Writes/updates/moves still happen.)
- *   - The live fetch returned 0 pages while files are tracked -> SUPPRESS
- *     (almost always a failed fetch, never a real "delete everything").
- *   - The plan would delete more than `MASS_DELETE_FRACTION` of a non-trivial
- *     vault -> SUPPRESS as a mass-deletion guard (defense in depth).
- *
- * Moves are NOT governed by this decision: a moved page IS present in `live`, so
- * its old-path removal is real (handled by the caller separately).
- */
-export function decideAbsenceDeletions(args) {
-    const { treeComplete, liveCount, existingCount, deleteCount } = args;
-    // No tracked files, or nothing to delete -> trivially fine to "apply".
-    if (existingCount === 0 || deleteCount === 0)
-        return { apply: true };
-    if (!treeComplete)
-        return { apply: false, reason: "incomplete-fetch" };
-    if (liveCount === 0)
-        return { apply: false, reason: "empty-live" };
-    if (existingCount >= MASS_DELETE_MIN_EXISTING &&
-        deleteCount > existingCount * MASS_DELETE_FRACTION) {
-        return { apply: false, reason: "mass-delete" };
-    }
-    return { apply: true };
-}

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

@@ -1,21 +0,0 @@
-/**
- * Pure, IO-free comparison helpers for the idempotency round-trip checks. The
- * round-trip harness that drives these lives in the package's tests, not in the
- * engine.
- */
-/**
- * Recursively strip every `attrs.id` from a ProseMirror node tree. Block ids
- * are regenerated by `markdownToProseMirror` (SPEC §11), so they must be
- * ignored when comparing the semantic shape of two documents. Returns a NEW
- * tree; the input is not mutated.
- */
-export declare function stripBlockIds(node: any): any;
-/**
- * Find the first divergence between two values via a recursive deep compare.
- * Returns a short path + the two differing values, or null if they are equal.
- */
-export declare function firstDivergence(a: any, b: any, path?: string): {
-    path: string;
-    a: any;
-    b: any;
-} | null;

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

@@ -1,70 +0,0 @@
-/**
- * Pure, IO-free comparison helpers for the idempotency round-trip checks. The
- * round-trip harness that drives these lives in the package's tests, not in the
- * engine.
- */
-/**
- * Recursively strip every `attrs.id` from a ProseMirror node tree. Block ids
- * are regenerated by `markdownToProseMirror` (SPEC §11), so they must be
- * ignored when comparing the semantic shape of two documents. Returns a NEW
- * tree; the input is not mutated.
- */
-export function stripBlockIds(node) {
-    if (Array.isArray(node)) {
-        return node.map(stripBlockIds);
-    }
-    if (node && typeof node === "object") {
-        const out = {};
-        for (const key of Object.keys(node)) {
-            if (key === "attrs" && node.attrs && typeof node.attrs === "object") {
-                // Drop the `id` attr; keep every other attribute.
-                const { id, ...rest } = node.attrs;
-                void id;
-                out.attrs = stripBlockIds(rest);
-            }
-            else {
-                out[key] = stripBlockIds(node[key]);
-            }
-        }
-        return out;
-    }
-    return node;
-}
-/**
- * Find the first divergence between two values via a recursive deep compare.
- * Returns a short path + the two differing values, or null if they are equal.
- */
-export function firstDivergence(a, b, path = "$") {
-    if (a === b)
-        return null;
-    const ta = typeof a;
-    const tb = typeof b;
-    if (ta !== tb || a === null || b === null) {
-        return { path, a, b };
-    }
-    if (ta !== "object") {
-        return { path, a, b };
-    }
-    const aIsArr = Array.isArray(a);
-    const bIsArr = Array.isArray(b);
-    if (aIsArr !== bIsArr)
-        return { path, a, b };
-    if (aIsArr) {
-        if (a.length !== b.length) {
-            return { path: `${path}.length`, a: a.length, b: b.length };
-        }
-        for (let i = 0; i < a.length; i++) {
-            const d = firstDivergence(a[i], b[i], `${path}[${i}]`);
-            if (d)
-                return d;
-        }
-        return null;
-    }
-    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
-    for (const k of keys) {
-        const d = firstDivergence(a[k], b[k], `${path}.${k}`);
-        if (d)
-            return d;
-    }
-    return null;
-}

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

@@ -1,23 +0,0 @@
-/**
- * Deterministic filename strategy (SPEC §12).
- *
- * The file name is COSMETIC — the source of truth for the file<->page link is
- * `pageId` / `slugId` inside the meta block, so renaming a file is safe. These
- * functions are intentionally dependency-free and pure, so they are trivially
- * unit-testable.
- */
-/**
- * Sanitize a page title into a safe file-name component (WITHOUT extension).
- *
- * Steps: replace forbidden / control characters with "-", collapse whitespace
- * runs to a single space, trim, cap the length, then guard against an empty
- * result, an all-dots result, or a reserved Windows device name by prefixing
- * with "_".
- */
-export declare function sanitizeTitle(title: string): string;
-/**
- * Disambiguate a sanitized name when two siblings in the same folder collapse
- * to the same name. Appends a stable suffix built from the page's `slugId`, so
- * the result stays deterministic across runs (SPEC §12: `Title ~slugId`).
- */
-export declare function disambiguate(name: string, slugId: string): string;