fix(temporary-notes): keep the banner usable on mobile (#321)

On narrow screens the temporary-note banner squeezed its text into a
one-word-per-line ladder and overflowing words slid under the subtle
"Move to trash" button. Two layout causes, both fixed here (layout-only; no
handler/logic/i18n changes):

- The text Group had `flex: 1` (= basis 0), so the outer `wrap="wrap"` never
  wrapped the buttons to a second row — it crushed the text instead. Give it a
  non-zero basis (`flex: 1 1 16rem`) so the wrap engages on narrow containers.
- Mirror DeletedPageBanner's adaptive actions: labeled Buttons visibleFrom="sm",
  icon-only ActionIcon + Tooltip + aria-label hiddenFrom="sm" (same handlers,
  loading flags, and t() keys). This also fixes the ru locale, whose long labels
  no longer render on mobile.

The sibling DeletedPageBanner already uses this pattern; adding the second button
in #273/#277 didn't carry the adaptive part over.

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

.env.example

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

AGENTS.md

@@ -72,7 +72,10 @@ git log -1 --format='Author: %an <%ae>%nCommitter: %cn <%ce>'
 
 ### 4. Push and PR to develop
 
-PRs always target `develop`. The `claude_code` password lives in the macOS
+PRs always target `develop`. Two different mechanisms are involved: **pushing
+commits is git-native** (the Gitea MCP cannot push local git history, so the
+branch is still pushed with `git push`), while **the PR itself is opened through
+the Gitea MCP** (see below). The `claude_code` password lives in the macOS
 keychain as a **generic password** under service `gitea-claude-code` (do not
 duplicate it as an internet-password for `gitea.vvzvlad.xyz` — that creates a
 conflict with the owner's account in the git credential helper):
@@ -94,18 +97,24 @@ git remote set-url gitea "$ORIG_URL"
 unset AGENT_PASS SAFE_PASS
 ```
 
-The PR is created via the Gitea REST API (Basic Auth as `claude_code`):
+The PR is opened through the **Gitea MCP** (server `gitea`), not `curl`/`tea` —
+the MCP authenticates in-process, so no keychain lookup or Basic-Auth is needed.
+Call `pull_request_write` with:
 
-```bash
-curl -s -X POST \
-  -u "claude_code:$(security find-generic-password -s gitea-claude-code -w)" \
-  -H "Content-Type: application/json" \
-  -d @pr_body.json \
-  "https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls"
-```
+- `method: "create"`
+- `owner: "vvzvlad"`, `repo: "gitmost"`
+- `base: "develop"`, `head: "<branch>"`
+- `title`, `body` — in the body: what was done, what is out of scope,
+  verification results (tsc/lint/tests).
 
-`base: develop`, `head: <branch>`. In the PR body: what was done, what is out
-of scope, verification results (tsc/lint/tests).
+Manage and read PRs through the same server: `list_pull_requests`,
+`pull_request_read` (`get`, `get_diff`, `get_files`, `get_status`),
+`pull_request_review_write`.
+
+**Identity note:** the MCP acts under its **own** configured Gitea token (verify
+with `get_me`), a different account from the `claude_code` used for git
+commits/pushes in §3. Only the forge API calls (PR / issue / review) go through
+the MCP account; the commits themselves stay authored as `claude_code`.
 
 > If push fails with `User permission denied for writing`, then `claude_code`
 > lacks collaborator rights on the repo. Ask the owner to add them (once, via
@@ -152,23 +161,25 @@ below.
 | Agent user (Gitea/git) | `claude_code` |
 | Agent email | `claude_code@vvzvlad.xyz` |
 | Keychain password | `security find-generic-password -s gitea-claude-code -w` |
-| PR API | `https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls` (here `gitmost` is the repo's real slug on the server) |
+| Forge API (PR / issue / review / reads) | **Gitea MCP** — server `gitea` (`pull_request_write`, `issue_write`, `list_pull_requests`, `pull_request_read`, `label_read`, …). Authenticated in-process; acts under its own token — check with `get_me`. Repo slug on the server is `gitmost`. |
 | Base branch | `develop` |
 | `origin` | GitHub mirror `vvzvlad/gitmost` — **do not push**, updated by the owner's CI |
 | `upstream` | The original Docmost — **never push** |
 
-## Creating issues (Gitea `tea` CLI)
+## Creating issues (Gitea MCP)
 
-Issues are filed with the official Gitea CLI `tea`, already logged in as
-`claude_code` (`tea logins list` shows the `gitea` login as default):
+File issues through the **Gitea MCP** (server `gitea`), not a CLI — call
+`issue_write` with:
 
-```bash
-tea issues create --repo vvzvlad/gitmost --labels feature \
-  --title '<title>' --description "$(cat body.md)"
-```
+- `method: "create"`
+- `owner: "vvzvlad"`, `repo: "gitmost"`
+- `title`, `body`
+- `labels` — an array of label **IDs** (numbers), *not* names. Resolve a name
+  such as `feature` to its id first with `label_read` (`method: "list"`), then
+  pass e.g. `labels: [<id>]`.
 
-> Gotcha (tea 0.14.1): the issue body flag is `--description`/`-d`, **not**
-> `--body` — passing `--body` fails with `flag provided but not defined: -body`.
+Read issues with `list_issues`, `issue_read`, or `search_issues`. The MCP is
+authenticated in-process, so no `tea`/`curl` and no keychain lookup are needed.
 
 ---
 

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

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

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

@@ -393,6 +393,17 @@
   "No speech detected": "Речь не распознана",
   "Transcription failed": "Не удалось распознать речь",
   "Voice dictation is not configured": "Голосовой ввод не настроен",
+  "Start dictation": "Начать диктовку",
+  "Stop recording": "Остановить запись",
+  "Microphone access denied": "Доступ к микрофону запрещён",
+  "No microphone found": "Микрофон не найден",
+  "Microphone is unavailable or already in use": "Микрофон недоступен или уже используется",
+  "Could not start recording": "Не удалось начать запись",
+  "Audio recording is not available in this browser/context": "Запись аудио недоступна в этом браузере/контексте",
+  "Dictation": "Диктовка",
+  "Dictation becomes available once the page finishes connecting": "Диктовка станет доступна после подключения к документу",
+  "No connection to the collaboration server — dictation unavailable": "Нет связи с сервером совместного редактирования — диктовка недоступна",
+  "This page is read-only": "Страница открыта только для чтения",
   "Embed PDF": "Встроить PDF",
   "Upload and embed a PDF file.": "Загрузите и встроите PDF-файл.",
   "Embed as PDF": "Встроить как PDF",
@@ -724,7 +735,8 @@
   "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
   "Delete this chat?": "Удалить этот чат?",
   "Deleted successfully": "Успешно удалено",
-  "Edited by AI agent on behalf of {{name}}": "Отредактировано AI-агентом от имени {{name}}",
+  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
+  "AI agent {{name}}": "AI-агент {{name}}",
   "Failed to delete chat": "Не удалось удалить чат",
   "Failed to rename chat": "Не удалось переименовать чат",
   "Failed": "Ошибка",
@@ -1228,5 +1240,10 @@
   "Updated to the latest version": "Обновлено до последней версии",
   "This role is no longer in the catalog": "Эта роль больше не представлена в каталоге",
   "This language is no longer available in the catalog": "Этот язык больше не доступен в каталоге",
-  "Connecting… (read-only)": "Подключение… (только чтение)"
+  "Connecting… (read-only)": "Подключение… (только чтение)",
+  "Apply": "Применить",
+  "Applied": "Применено",
+  "Suggestion applied": "Предложение применено",
+  "Failed to apply suggestion": "Не удалось применить предложение",
+  "The commented text changed since this suggestion was made; it was not applied.": "Прокомментированный текст изменился после создания предложения; оно не было применено."
 }

apps/client/src/components/common/export-modal.tsx

@@ -14,6 +14,22 @@ import { notifications } from "@mantine/notifications";
 import { exportSpace } from "@/features/space/services/space-service";
 import { useTranslation } from "react-i18next";
 
+// The export request uses `responseType: "blob"`, so a server error body arrives
+// as a Blob rather than parsed JSON — `err.response?.data.message` is therefore
+// always undefined. Read and parse the blob to surface the real error message.
+async function extractExportError(err: any): Promise<string> {
+  const data = err?.response?.data;
+  if (data instanceof Blob) {
+    try {
+      const json = JSON.parse(await data.text());
+      return json?.message ?? "";
+    } catch {
+      return "";
+    }
+  }
+  return data?.message ?? err?.message ?? "";
+}
+
 interface ExportModalProps {
   id: string;
   type: "space" | "page";
@@ -52,8 +68,9 @@ export default function ExportModal({
       });
       onClose();
     } catch (err) {
+      const message = await extractExportError(err);
       notifications.show({
-        message: "Export failed:" + err.response?.data.message,
+        message: t("Export failed") + (message ? `: ${message}` : ""),
         color: "red",
       });
       console.error("export error", err);

apps/client/src/components/layouts/global/app-header.tsx

@@ -12,6 +12,7 @@ import TopMenu from "@/components/layouts/global/top-menu.tsx";
 import { Link } from "react-router-dom";
 import { useAtom } from "jotai";
 import {
+  NAVBAR_COLLAPSE_BREAKPOINT,
   desktopSidebarAtom,
   mobileSidebarAtom,
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
@@ -53,7 +54,13 @@ export function AppHeader() {
               aria-label={t("Sidebar toggle")}
               opened={mobileOpened}
               onClick={toggleMobile}
-              hiddenFrom="sm"
+              // Must match the AppShell navbar breakpoint (md). The navbar
+              // collapses to the MOBILE drawer below md, so the mobile toggle
+              // (which flips mobileOpened) must be the one visible across the
+              // whole <md band — otherwise at 768-991 the desktop toggle showed
+              // but flipped the wrong atom, leaving the drawer unopenable (the
+              // regression from the initial sm->md navbar change).
+              hiddenFrom={NAVBAR_COLLAPSE_BREAKPOINT}
               size="sm"
             />
           </Tooltip>
@@ -63,7 +70,7 @@ export function AppHeader() {
               aria-label={t("Sidebar toggle")}
               opened={desktopOpened}
               onClick={toggleDesktop}
-              visibleFrom="sm"
+              visibleFrom={NAVBAR_COLLAPSE_BREAKPOINT}
               size="sm"
             />
           </Tooltip>

apps/client/src/components/layouts/global/global-app-shell.tsx

@@ -6,6 +6,7 @@ import SettingsSidebar from "@/components/settings/settings-sidebar.tsx";
 import { useAtom } from "jotai";
 import {
   APP_NAVBAR_ID,
+  NAVBAR_COLLAPSE_BREAKPOINT,
   asideStateAtom,
   desktopSidebarAtom,
   mobileSidebarAtom,
@@ -88,7 +89,13 @@ export default function GlobalAppShell({
       header={{ height: 45 }}
       navbar={{
         width: isSpaceRoute ? sidebarWidth : 300,
-        breakpoint: "sm",
+        // `md` (not `sm`): below 992px the fixed ~300px sidebar leaves too little
+        // room for content — the settings tables (Members/…) overflow the offset
+        // content area on tablet (~768px) and clip the Role/actions columns
+        // off-screen with no horizontal scroll. Collapsing the navbar to a toggle
+        // drawer across the whole tablet band frees the full width for content
+        // (the mobile drawer is closed by default, so nothing overlaps on load).
+        breakpoint: NAVBAR_COLLAPSE_BREAKPOINT,
         collapsed: {
           mobile: !mobileOpened,
           desktop: !desktopOpened,
@@ -97,7 +104,7 @@ export default function GlobalAppShell({
       aside={
         isPageRoute && {
           width: 420,
-          breakpoint: "sm",
+          breakpoint: "md",
           collapsed: { mobile: !isAsideOpen, desktop: !isAsideOpen },
         }
       }

apps/client/src/components/layouts/global/hooks/atoms/sidebar-atom.ts

@@ -7,6 +7,13 @@ import { atom } from "jotai";
 // would create a shell -> chat-window -> shell import cycle).
 export const APP_NAVBAR_ID = "app-shell-navbar";
 
+// Single source of truth for the navbar collapse breakpoint. The AppShell navbar
+// `breakpoint` and BOTH burger toggles' `hiddenFrom`/`visibleFrom` MUST use this
+// exact value: if they drift, the sidebar becomes unreachable on tablet widths
+// (the round-1 regression of #292). Kept here so the shell and the header share
+// one constant the compiler enforces, instead of three hand-synced string literals.
+export const NAVBAR_COLLAPSE_BREAKPOINT = "md";
+
 export const mobileSidebarAtom = atom<boolean>(false);
 
 export const desktopSidebarAtom = atomWithWebStorage<boolean>(

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

@@ -0,0 +1,206 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { Provider, createStore } from "jotai";
+import { AgentAvatarStack, agentGlyphBackground } from "./agent-avatar-stack";
+import {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+type Props = React.ComponentProps<typeof AgentAvatarStack>;
+
+// The DOM normalizes an inline `background: hsl(...)` 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).
+function normalizeColor(value: string): string {
+  const probe = document.createElement("div");
+  probe.style.background = value;
+  return probe.style.background;
+}
+
+function renderStack(props: Props) {
+  const store = createStore();
+  store.set(aiChatDraftAtom, "leftover draft from another chat");
+  const utils = render(
+    <Provider store={store}>
+      <MantineProvider>
+        <AgentAvatarStack {...props} />
+      </MantineProvider>
+    </Provider>,
+  );
+  return { store, ...utils };
+}
+
+describe("agentGlyphBackground", () => {
+  it("is deterministic for a given agent name", () => {
+    expect(agentGlyphBackground("Researcher")).toBe(
+      agentGlyphBackground("Researcher"),
+    );
+  });
+
+  it("gives categorically different colors to different agents", () => {
+    // The two agents that looked identically violet in the report must differ.
+    expect(agentGlyphBackground("Структурный редактор")).not.toBe(
+      agentGlyphBackground("Фактчекер"),
+    );
+    expect(agentGlyphBackground("Researcher")).not.toBe(
+      agentGlyphBackground("Нарратор"),
+    );
+    // Every color is a dark hsl circle drawn from the palette.
+    expect(agentGlyphBackground("Нарратор")).toMatch(/^hsl\(\d+, \d+%, \d+%\)$/);
+  });
+});
+
+describe("AgentAvatarStack", () => {
+  it("internal chat WITH role: emoji glyph + human launcher badge in front", () => {
+    const { container } = renderStack({
+      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+      launcher: { name: "Alice", avatarUrl: null },
+      aiChatId: "chat-1",
+    });
+
+    // Emoji is used as the glyph (priority 2), NOT the sparkles fallback.
+    expect(screen.getByText("🔬")).toBeDefined();
+    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
+    // Label: bold role name + dimmed "· launcher".
+    expect(screen.getByText("Researcher")).toBeDefined();
+    expect(screen.getByText(/·/)).toBeDefined();
+    expect(screen.getByText("Alice")).toBeDefined();
+  });
+
+  it("emoji glyph applies its per-agent color as an inline DOM background", () => {
+    // Pins the actual fix: the hashed color 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();
+    // Non-vacuous: compare against the function output (normalized the same way),
+    // not a frozen literal. Empty against the pre-fix Avatar (no inline bg).
+    expect(glyph!.style.background).not.toBe("");
+    expect(glyph!.style.background).toBe(
+      normalizeColor(agentGlyphBackground(agent.name)),
+    );
+  });
+
+  it("agents with distinct hashed colors 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(agentGlyphBackground("Researcher")).not.toBe(
+      agentGlyphBackground("Нарратор"),
+    );
+
+    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.background).toBe(
+      normalizeColor(agentGlyphBackground("Researcher")),
+    );
+    expect(glyphB!.style.background).toBe(
+      normalizeColor(agentGlyphBackground("Нарратор")),
+    );
+    // Different colors reach the DOM (the normalized rgb values also differ).
+    expect(glyphA!.style.background).not.toBe(glyphB!.style.background);
+  });
+
+  it("showName=false: renders only the avatars, no inline name label", () => {
+    renderStack({
+      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+      launcher: { name: "Alice", avatarUrl: null },
+      aiChatId: "chat-1",
+      showName: false,
+    });
+
+    // The agent glyph is still rendered...
+    expect(screen.getByText("🔬")).toBeDefined();
+    // ...but neither the agent NOR the launcher inline name label is rendered
+    // (they live only in the hover tooltip, which is not mounted in the initial
+    // DOM) — guards against suppressing only the agent name and leaking the
+    // launcher name.
+    expect(screen.queryByText("Researcher")).toBeNull();
+    expect(screen.queryByText("Alice")).toBeNull();
+  });
+
+  it("internal chat WITHOUT role: sparkles fallback + 'AI agent' + launcher", () => {
+    const { container } = renderStack({
+      agent: { name: "AI agent", avatarUrl: null },
+      launcher: { name: "Bob", avatarUrl: null },
+      aiChatId: "chat-2",
+    });
+
+    // No avatarUrl and no emoji => sparkles glyph (priority 3).
+    expect(container.querySelector(".tabler-icon-sparkles")).not.toBeNull();
+    expect(screen.getByText("AI agent")).toBeDefined();
+    expect(screen.getByText("Bob")).toBeDefined();
+  });
+
+  it("external MCP: agent avatar only, NO human launcher badge", () => {
+    const { container } = renderStack({
+      agent: { name: "MCP Bot", avatarUrl: "http://example.test/a.png" },
+      launcher: null,
+      aiChatId: null,
+    });
+
+    // avatarUrl provided (priority 1) => not the sparkles fallback.
+    expect(container.querySelector(".tabler-icon-sparkles")).toBeNull();
+    expect(screen.getByText("MCP Bot")).toBeDefined();
+    // No human behind => no "·" separator is rendered.
+    expect(screen.queryByText(/·/)).toBeNull();
+    // No internal chat => the stack is not an interactive deep-link button.
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("click deep-links into the chat when aiChatId is present", () => {
+    const { store } = renderStack({
+      agent: { name: "Researcher", emoji: "🔬", avatarUrl: null },
+      launcher: { name: "Alice", avatarUrl: null },
+      aiChatId: "chat-1",
+    });
+
+    const button = screen.getByRole("button");
+    fireEvent.click(button);
+
+    expect(store.get(activeAiChatIdAtom)).toBe("chat-1");
+    expect(store.get(aiChatWindowOpenAtom)).toBe(true);
+    expect(store.get(aiChatDraftAtom)).toBe(""); // draft cleared on switch
+  });
+
+  it("click is a no-op / not interactive without a chat target", () => {
+    const onActivate = vi.fn();
+    renderStack({
+      agent: { name: "MCP Bot", avatarUrl: "http://example.test/a.png" },
+      launcher: null,
+      aiChatId: null,
+      onActivate,
+    });
+    expect(screen.queryByRole("button")).toBeNull();
+    expect(onActivate).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,267 @@
+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 {
+  activeAiChatIdAtom,
+  aiChatWindowOpenAtom,
+  aiChatDraftAtom,
+} from "@/features/ai-chat/atoms/ai-chat-atom.ts";
+
+// The FRONT identity (the acting agent) and the BEHIND identity (the human who
+// launched it). Both are computed server-side (#300) so the client never branches
+// on the internal-vs-MCP provenance — it just renders whatever it is handed.
+export interface AgentInfo {
+  name: string;
+  emoji?: string | null;
+  avatarUrl?: string | null;
+}
+export interface LauncherInfo {
+  name: string;
+  avatarUrl?: string | null;
+}
+
+const GLYPH_SIZE = 38;
+const LAUNCHER_SIZE = 22;
+// How far the launcher avatar sticks out past the agent's top-right corner — it
+// sits as a small badge over that corner (above the glyph) and stays fully visible.
+const LAUNCHER_OVERHANG = 8;
+
+// Small deterministic string hash (same algorithm as custom-avatar's initials
+// hash) used to pick a stable per-agent glyph color.
+function hashName(input: string): number {
+  let hash = 0;
+  for (let i = 0; i < input.length; i += 1) {
+    hash = (hash << 5) - hash + input.charCodeAt(i);
+    hash |= 0;
+  }
+  return Math.abs(hash);
+}
+
+// A palette of categorically-DISTINCT dark circle colors for emoji/sparkles agent
+// glyphs. Every entry is intentionally dark (low lightness) so a bright emoji or
+// the white sparkles icon stays readable on top; the hues are spread across the
+// wheel (red → orange → amber → green → teal → cyan → blue → indigo → violet →
+// magenta + a neutral slate) so two different agents read as DIFFERENT colors,
+// not merely different shades of the same violet.
+const GLYPH_COLORS = [
+  "hsl(355, 60%, 34%)", // red
+  "hsl(18, 62%, 32%)", // vermilion
+  "hsl(32, 60%, 30%)", // orange
+  "hsl(45, 55%, 28%)", // amber
+  "hsl(75, 45%, 26%)", // olive-green
+  "hsl(140, 48%, 26%)", // green
+  "hsl(165, 52%, 26%)", // teal
+  "hsl(188, 58%, 28%)", // cyan
+  "hsl(205, 58%, 32%)", // sky blue
+  "hsl(225, 52%, 36%)", // blue
+  "hsl(250, 48%, 38%)", // indigo
+  "hsl(280, 46%, 36%)", // violet
+  "hsl(312, 48%, 34%)", // magenta
+  "hsl(210, 12%, 36%)", // slate / neutral
+];
+
+/**
+ * Deterministic dark circle color for an emoji/sparkles agent glyph, picked from
+ * GLYPH_COLORS by a hash of the agent name so distinct agents get categorically
+ * distinct colors while every color stays dark enough to keep the glyph readable.
+ */
+export function agentGlyphBackground(name: string): string {
+  return GLYPH_COLORS[hashName(name) % GLYPH_COLORS.length];
+}
+
+/**
+ * The front avatar. Image-source priority (#300):
+ *   1. agent.avatarUrl -> a real avatar image (external MCP agent account).
+ *   2. agent.emoji     -> the role emoji on a per-agent dark circle.
+ *   3. otherwise       -> the IconSparkles glyph on a per-agent dark circle (fallback).
+ */
+function AgentGlyph({ agent }: { agent: AgentInfo }) {
+  if (agent.avatarUrl) {
+    return (
+      <CustomAvatar
+        size={GLYPH_SIZE}
+        avatarUrl={agent.avatarUrl}
+        name={agent.name}
+      />
+    );
+  }
+
+  // Emoji/sparkles glyph on a per-agent dark circle (color hashed from the agent
+  // name). Rendered as a plain Box, NOT a Mantine `Avatar variant="filled"`, so
+  // the background is guaranteed instead of being overridden by Mantine's
+  // `--avatar-bg` (which was falling back to the theme's violet for every agent).
+  return (
+    <Box
+      data-testid="agent-glyph"
+      style={{
+        width: GLYPH_SIZE,
+        height: GLYPH_SIZE,
+        borderRadius: "50%",
+        background: agentGlyphBackground(agent.name),
+        color: "var(--mantine-color-white)",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        lineHeight: 1,
+      }}
+    >
+      {agent.emoji ? (
+        <span style={{ fontSize: Math.round(GLYPH_SIZE * 0.5) }} aria-hidden>
+          {agent.emoji}
+        </span>
+      ) : (
+        <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
+      )}
+    </Box>
+  );
+}
+
+export interface AgentAvatarStackProps {
+  agent: AgentInfo;
+  // null/absent => external MCP (front agent avatar only, no human behind).
+  launcher?: LauncherInfo | null;
+  // Deep-links into the internal AI chat when present (null for external MCP).
+  aiChatId?: string | null;
+  // Fired after the stack deep-links into its chat, so the caller can react
+  // (e.g. the page-history row closes the history modal). Keeps this ui/ primitive
+  // free of cross-feature coupling (inherited from the old AiAgentBadge, #143).
+  onActivate?: () => void;
+  // Whether to render the inline name label next to the avatars (default true).
+  // Set false when the caller renders the name itself (e.g. the comment row).
+  showName?: boolean;
+}
+
+/**
+ * The "agent avatar stack" (#300): the AGENT glyph, and — for an internal AI
+ * chat — the HUMAN who launched it as a smaller avatar badge on top, overhanging
+ * the glyph's top-right corner in FRONT (zIndex 2 > the glyph's zIndex 1) so the
+ * launcher stays fully visible rather than being half-hidden behind the glyph.
+ * Replaces the old text `AI-agent` badge. When the item carries an `aiChatId` the
+ * whole stack is a deep-link into that chat (the click the old badge owned moved
+ * here); the click is contained (stopPropagation) so it does not also trigger an
+ * enclosing row handler.
+ */
+export function AgentAvatarStack({
+  agent,
+  launcher,
+  aiChatId,
+  onActivate,
+  showName = true,
+}: AgentAvatarStackProps) {
+  const { t } = useTranslation();
+  const setAiChatWindowOpen = useSetAtom(aiChatWindowOpenAtom);
+  const setActiveChatId = useSetAtom(activeAiChatIdAtom);
+  const setDraft = useSetAtom(aiChatDraftAtom);
+
+  const clickable = !!aiChatId;
+
+  const openChat = useCallback(
+    (event: React.SyntheticEvent) => {
+      event.stopPropagation();
+      if (!aiChatId) return;
+      setActiveChatId(aiChatId);
+      // Switching chats must start with a clean composer — clear any unsent draft
+      // so it does not leak from the previously open chat.
+      setDraft("");
+      setAiChatWindowOpen(true);
+      onActivate?.();
+    },
+    [aiChatId, setActiveChatId, setDraft, setAiChatWindowOpen, onActivate],
+  );
+
+  // Internal chat => "role on behalf of person"; external MCP => just the agent.
+  const tooltip = launcher
+    ? t("AI agent «{{role}}» on behalf of {{person}}", {
+        role: agent.name,
+        person: launcher.name,
+      })
+    : t("AI agent {{name}}", { name: agent.name });
+
+  // The container is only enlarged when there is a launcher to overhang; with no
+  // human behind it stays tight at the agent glyph size.
+  const stackSize = launcher ? GLYPH_SIZE + LAUNCHER_OVERHANG : GLYPH_SIZE;
+
+  const stack = (
+    <Box
+      pos="relative"
+      style={{
+        width: stackSize,
+        height: stackSize,
+        flexShrink: 0,
+        // Center the (in-flow) agent glyph vertically so it lines up with its
+        // name label; the absolutely-positioned launcher is unaffected by flex.
+        display: "flex",
+        alignItems: "center",
+        cursor: clickable ? "pointer" : undefined,
+      }}
+      {...(clickable
+        ? {
+            role: "button",
+            tabIndex: 0,
+            onClick: openChat,
+            onKeyDown: (event: React.KeyboardEvent) => {
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+                openChat(event);
+              }
+            },
+          }
+        : {})}
+    >
+      {launcher && (
+        // Launcher badge sits ABOVE the agent glyph (zIndex) at the top-right so
+        // it is fully visible, not half-hidden behind the agent circle.
+        <Box pos="absolute" top={0} right={0} style={{ zIndex: 2 }}>
+          <CustomAvatar
+            size={LAUNCHER_SIZE}
+            avatarUrl={launcher.avatarUrl}
+            name={launcher.name}
+            style={{ border: "2px solid var(--mantine-color-body)" }}
+          />
+        </Box>
+      )}
+      {/* The agent glyph keeps its own size (flex-centered in the container); the
+          launcher overhangs it by LAUNCHER_OVERHANG at the top-right and stays visible. */}
+      <Box
+        style={{
+          position: "relative",
+          zIndex: 1,
+          width: GLYPH_SIZE,
+          height: GLYPH_SIZE,
+        }}
+      >
+        <AgentGlyph agent={agent} />
+      </Box>
+    </Box>
+  );
+
+  return (
+    <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
+      <Tooltip label={tooltip} withArrow>
+        {stack}
+      </Tooltip>
+      {showName && (
+        <Group gap={4} wrap="nowrap" style={{ minWidth: 0 }}>
+          <Text size="xs" fw={600} lineClamp={1} lh={1.2}>
+            {agent.name}
+          </Text>
+          {launcher && (
+            <>
+              <Text size="xs" c="dimmed" fw={400} aria-hidden>
+                ·
+              </Text>
+              <Text size="xs" c="dimmed" fw={400} lineClamp={1} lh={1.2}>
+                {launcher.name}
+              </Text>
+            </>
+          )}
+        </Group>
+      )}
+    </Group>
+  );
+}
+
+export default AgentAvatarStack;

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

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

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

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

apps/client/src/features/ai-chat/components/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,6 +24,7 @@ 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.
 
@@ -62,4 +70,18 @@ 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);
+  });
 });

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

@@ -34,15 +34,19 @@ function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
   // Authoritative count wins; otherwise estimate live from the streamed text.
   const count = tokens && tokens > 0 ? tokens : estimateTokens(text);
   const trimmed = text.trim();
-  // Memoize the markdown render so toggling `open` (or a parent re-render caused
-  // by an unrelated streamed delta) does not re-parse the reasoning text; it
-  // recomputes only when the reasoning text itself changes (while it streams in).
-  // collapseBlankLines collapses the blank-line gaps the model emits between every
-  // list item / paragraph so the reasoning renders compactly (tight lists, joined
-  // paragraphs) — ONLY here, not in the normal answer.
+  // Parse the reasoning markdown ONLY while the block is expanded. Collapsed is the
+  // default and the common case during a long "thinking" stream: reasoning text
+  // streams in and grows with every throttled delta (~20Hz), so a `[trimmed]`-only
+  // memo re-parses the whole, ever-growing text (marked + DOMPurify) on every delta
+  // — an O(n²) storm that pins the main thread and freezes the chat, all for a block
+  // the user isn't even looking at (the html is only shown inside <Collapse in={open}>
+  // below). Gating on `open` skips that hidden parsing entirely; expanding parses the
+  // current text once (an instant, user-initiated click), and further streaming while
+  // open is the normal per-delta append render, like the answer.
   const html = useMemo(
-    () => (trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : ""),
-    [trimmed],
+    () =>
+      open && trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : "",
+    [open, trimmed],
   );
 
   return (

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/auth/hooks/use-auth.ts

@@ -23,6 +23,7 @@ import { acceptInvitation } from "@/features/workspace/services/workspace-servic
 import APP_ROUTE, { getPostLoginRedirect } from "@/lib/app-route.ts";
 import { RESET } from "jotai/utils";
 import { useTranslation } from "react-i18next";
+import { clearPersistedTreeCaches } from "@/features/page/tree/atoms/tree-data-atom";
 
 export default function useAuth() {
   const { t } = useTranslation();
@@ -122,6 +123,11 @@ export default function useAuth() {
 
   const handleLogout = async () => {
     setCurrentUser(RESET);
+    // Purge the persisted sidebar tree caches (they contain page titles) so the
+    // cached page titles aren't left readable in localStorage on a shared
+    // machine. (Only the tree caches are swept; other localStorage entries
+    // remain.)
+    clearPersistedTreeCaches();
     await logout();
     window.location.replace(`${APP_ROUTE.AUTH.LOGIN}?logout=1`);
   };

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

apps/client/src/features/editor/extensions/custom-typography.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect } from "vitest";
+import { Editor } from "@tiptap/core";
+import { Document } from "@tiptap/extension-document";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Text } from "@tiptap/extension-text";
+import { ySyncPluginKey } from "@tiptap/y-tiptap";
+import {
+  CustomTypography,
+  undoGuardKey,
+  findChangedRange,
+  mapRangeThroughChange,
+} from "./custom-typography";
+
+/**
+ * PR #296 — the collab-safe typography undo-guard is exercised through the REAL
+ * editor path: a fresh Editor with the CustomTypography extension, transactions
+ * tagged exactly the way prosemirror-history / y-tiptap tag undo & remote
+ * changes (`setMeta("history$", …)` and `setMeta(ySyncPluginKey, …)`), plus
+ * direct unit tests of the two pure diff helpers. No hand-poke of plugin state.
+ *
+ * ARMING MECHANISM (verified against custom-typography.ts source):
+ *   - A transaction arms the guard only when it is BOTH history/remote
+ *     (`getMeta("history$")` truthy, or `isChangeOrigin` via the ySync meta)
+ *     AND an undo/redo (`getMeta("history$")` truthy, or ySync
+ *     `isUndoRedoOperation`), AND its whole-doc diff is a REPLACE
+ *     (change.oldTo > change.from && change.newTo > change.from).
+ *   - `history$` is the stringified PluginKey of the single prosemirror-history
+ *     plugin; ProseMirror stores meta under `key.key`, so setMeta("history$")
+ *     in a test is read identically by the extension's getMeta("history$").
+ */
+
+const singlePara = (text: string) => ({
+  type: "doc",
+  content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+});
+
+const makeEditor = (text: string) =>
+  new Editor({
+    extensions: [Document, Paragraph, Text, CustomTypography],
+    content: singlePara(text),
+  });
+
+// Build a before/after EditorState pair by applying one plain transaction.
+const mutate = (text: string, apply: (tr: any, schema: any) => void) => {
+  const editor = new Editor({
+    extensions: [Document, Paragraph, Text],
+    content: singlePara(text),
+  });
+  const before = editor.state;
+  const tr = before.tr;
+  apply(tr, before.schema);
+  editor.view.dispatch(tr);
+  const after = editor.state;
+  return { before, after, editor };
+};
+
+describe("findChangedRange", () => {
+  it("returns null for identical docs", () => {
+    const editor = new Editor({
+      extensions: [Document, Paragraph, Text],
+      content: singlePara("hello"),
+    });
+    expect(findChangedRange(editor.state, editor.state)).toBeNull();
+    editor.destroy();
+  });
+
+  it("returns the minimal range for a normal middle insertion", () => {
+    // "hello world" (text at 1..12); insert "there " at pos 6.
+    const { before, after, editor } = mutate("hello world", (tr) =>
+      tr.insertText("there ", 6),
+    );
+    expect(findChangedRange(before, after)).toEqual({
+      from: 6,
+      oldTo: 6,
+      newTo: 12,
+    });
+    editor.destroy();
+  });
+
+  it("normalizes the INSERTION overlapping-bounds branch (repeated content)", () => {
+    // Insert one more 'a' into "aaaaa" at pos 3. findDiffStart lands at the end
+    // (6) while findDiffEnd reports an end BEFORE it ({a:1,b:2}); both ends must
+    // be pushed forward by the same delta -> a non-degenerate range.
+    const { before, after, editor } = mutate("aaaaa", (tr) =>
+      tr.insertText("a", 3),
+    );
+    const change = findChangedRange(before, after)!;
+    expect(change).toEqual({ from: 6, oldTo: 6, newTo: 7 });
+    // Invariant the guard logic relies on: never degenerate.
+    expect(change.from).toBeLessThanOrEqual(change.oldTo);
+    expect(change.from).toBeLessThanOrEqual(change.newTo);
+    editor.destroy();
+  });
+
+  it("normalizes the DELETION overlapping-bounds branch (F2 fix)", () => {
+    // Delete one repeated 'a' from the middle of "aaaaa" ([3,4)). Here
+    // findDiffEnd reports newTo < start, the symmetric case the old one-sided
+    // normalization missed -> it used to yield a degenerate range (newTo < from).
+    const { before, after, editor } = mutate("aaaaa", (tr) => tr.delete(3, 4));
+    const change = findChangedRange(before, after)!;
+    expect(change).toEqual({ from: 5, oldTo: 6, newTo: 5 });
+    // The whole point of F2: from <= newTo (and from <= oldTo) still holds.
+    expect(change.from).toBeLessThanOrEqual(change.newTo);
+    expect(change.from).toBeLessThanOrEqual(change.oldTo);
+    editor.destroy();
+  });
+
+  it("normalizes a multi-char repeated deletion (F2 fix)", () => {
+    const { before, after, editor } = mutate("aaaaa", (tr) => tr.delete(2, 4));
+    const change = findChangedRange(before, after)!;
+    expect(change).toEqual({ from: 4, oldTo: 6, newTo: 4 });
+    expect(change.from).toBeLessThanOrEqual(change.newTo);
+    editor.destroy();
+  });
+});
+
+describe("mapRangeThroughChange", () => {
+  const range = { from: 5, to: 10 };
+
+  it("RELEASES on a strict intersection (edit inside the guarded range)", () => {
+    // change straddles the interior of the guard.
+    expect(
+      mapRangeThroughChange(range, { from: 6, oldTo: 8, newTo: 7 }),
+    ).toBeNull();
+  });
+
+  it("does NOT release on a boundary touch at the guard END", () => {
+    // Edit begins exactly at range.to (10): from < to is false -> no intersect.
+    expect(
+      mapRangeThroughChange(range, { from: 10, oldTo: 10, newTo: 12 }),
+    ).toEqual(range);
+  });
+
+  it("does NOT release on a boundary touch at the guard START", () => {
+    // Edit ends exactly at range.from (5): oldTo > from is false -> no intersect;
+    // it is treated as a change fully before, shifting the guard.
+    expect(
+      mapRangeThroughChange(range, { from: 3, oldTo: 5, newTo: 8 }),
+    ).toEqual({ from: 8, to: 13 });
+  });
+
+  it("SHIFTS the guard for a change fully before it", () => {
+    // Insert 2 chars entirely before the range (oldTo 3 <= from 5): +2 delta.
+    expect(
+      mapRangeThroughChange(range, { from: 2, oldTo: 3, newTo: 5 }),
+    ).toEqual({ from: 7, to: 12 });
+  });
+
+  it("leaves the guard untouched for a change fully after it", () => {
+    expect(
+      mapRangeThroughChange(range, { from: 12, oldTo: 14, newTo: 16 }),
+    ).toBe(range);
+  });
+});
+
+describe("undo-guard arming (integration)", () => {
+  it("arms {from, to:newTo} on a LOCAL undo-replace (history meta)", () => {
+    // Undo of an em-dash substitution: "a—b" restored to "a--b" — the em-dash
+    // (pos 2..3) is REPLACED by "--", tagged with the history plugin's meta.
+    const editor = makeEditor("a—b");
+    const { state } = editor;
+    const tr = state.tr
+      .replaceWith(2, 3, state.schema.text("--"))
+      .setMeta("history$", { redo: false });
+    editor.view.dispatch(tr);
+
+    expect(editor.state.doc.textContent).toBe("a--b");
+    // from = diff start (2), to = newTo = end of the inserted "--" (4).
+    expect(undoGuardKey.getState(editor.state)).toEqual({ from: 2, to: 4 });
+    editor.destroy();
+  });
+
+  it("does NOT arm on a REMOTE change-origin replace (no undo meta)", () => {
+    // Same replace, but tagged only as a y-sync remote change: history/remote
+    // yes, undo/redo NO -> must not arm.
+    const editor = makeEditor("a—b");
+    const { state } = editor;
+    const tr = state.tr
+      .replaceWith(2, 3, state.schema.text("--"))
+      .setMeta(ySyncPluginKey, { isChangeOrigin: true });
+    editor.view.dispatch(tr);
+
+    expect(editor.state.doc.textContent).toBe("a--b");
+    expect(undoGuardKey.getState(editor.state)).toBeNull();
+    editor.destroy();
+  });
+
+  it("does NOT arm on an ordinary local edit", () => {
+    const editor = makeEditor("a—b");
+    editor.view.dispatch(
+      editor.state.tr.replaceWith(2, 3, editor.state.schema.text("--")),
+    );
+    expect(undoGuardKey.getState(editor.state)).toBeNull();
+    editor.destroy();
+  });
+});
+
+describe("undo-guard release / shift (integration)", () => {
+  it("RELEASES when a later edit lands inside the guarded region", () => {
+    const editor = makeEditor("a—b");
+    editor.view.dispatch(
+      editor.state.tr
+        .replaceWith(2, 3, editor.state.schema.text("--"))
+        .setMeta("history$", { redo: false }),
+    );
+    const guard = undoGuardKey.getState(editor.state)!;
+    expect(guard).toEqual({ from: 2, to: 4 });
+
+    // Type a character inside the restored region -> guard is dropped.
+    editor.view.dispatch(editor.state.tr.insertText("x", guard.from + 1));
+    expect(undoGuardKey.getState(editor.state)).toBeNull();
+    editor.destroy();
+  });
+
+  it("keeps and SHIFTS the guard when a later edit lands before it", () => {
+    const editor = makeEditor("zz a—b");
+    // "zz a—b": em-dash at pos 5; replace the 'a' at 4..5 with "--" to arm.
+    editor.view.dispatch(
+      editor.state.tr
+        .replaceWith(4, 5, editor.state.schema.text("--"))
+        .setMeta("history$", { redo: false }),
+    );
+    const guard = undoGuardKey.getState(editor.state)!;
+    expect(guard).toEqual({ from: 4, to: 6 });
+
+    // Insert one char at the very start (before the guard) -> guard shifts +1.
+    editor.view.dispatch(editor.state.tr.insertText("Q", 1));
+    expect(undoGuardKey.getState(editor.state)).toEqual({ from: 5, to: 7 });
+    editor.destroy();
+  });
+});

apps/client/src/features/editor/extensions/custom-typography.ts

@@ -0,0 +1,193 @@
+import { InputRule } from "@tiptap/core";
+import {
+  Plugin,
+  PluginKey,
+  type EditorState,
+  type Transaction,
+} from "@tiptap/pm/state";
+import { Typography } from "@tiptap/extension-typography";
+import { isChangeOrigin } from "@tiptap/extension-collaboration";
+import { ySyncPluginKey } from "@tiptap/y-tiptap";
+
+// Region restored by the latest undo — while it is intact, typography
+// input rules overlapping it must not fire again.
+interface UndoGuardRange {
+  from: number;
+  to: number;
+}
+
+// Exported for tests: the plugin key lets a test read the armed guard state,
+// and the two pure helpers below are unit-tested directly.
+export const undoGuardKey = new PluginKey<UndoGuardRange | null>(
+  "typographyUndoGuard",
+);
+
+// prosemirror-history does not export its plugin key, so template-editor
+// undo/redo is detected via the stable stringified key. Only one
+// PluginKey("history") exists in the dependency tree, so "history$" is stable.
+const HISTORY_META = "history$";
+
+const isUndoRedoTransaction = (tr: Transaction): boolean => {
+  if (tr.getMeta(HISTORY_META)) {
+    return true;
+  }
+  // Read yjs undo/redo meta via the real ySyncPluginKey object (imported, not
+  // a fragile stringified key), which y-tiptap sets on Y.UndoManager changes.
+  const ySyncMeta = tr.getMeta(ySyncPluginKey) as
+    | { isUndoRedoOperation?: boolean }
+    | undefined;
+  return !!ySyncMeta?.isUndoRedoOperation;
+};
+
+interface DocChange {
+  from: number;
+  oldTo: number;
+  newTo: number;
+}
+
+// Compute the minimal changed region between two docs. yjs undo/redo (and any
+// remote change) arrives as a whole-document replace step, so the transaction
+// step maps are useless — diff the docs to recover the real minimal change.
+// Returns null when the docs are identical.
+export const findChangedRange = (
+  oldState: EditorState,
+  newState: EditorState,
+): DocChange | null => {
+  const start = oldState.doc.content.findDiffStart(newState.doc.content);
+  const end = oldState.doc.content.findDiffEnd(newState.doc.content);
+  if (start == null || end == null) {
+    return null;
+  }
+  let { a: oldTo, b: newTo } = end;
+  // findDiffEnd can report an end BEFORE the diff start when the changed text
+  // abuts repeated content (insertion -> oldTo<start, deletion -> newTo<start).
+  // Push both ends forward by the same delta so the range stays non-degenerate
+  // (from <= oldTo and from <= newTo), matching ProseMirror's own diff bounds.
+  const minTo = Math.min(oldTo, newTo);
+  if (minTo < start) {
+    const delta = start - minTo;
+    oldTo += delta;
+    newTo += delta;
+  }
+  return { from: start, oldTo, newTo };
+};
+
+// Map an armed guard range across a single document change described by a diff.
+// Returns null when the change touches the guarded text itself (the restored
+// substitution was edited, so the guard must be released).
+export const mapRangeThroughChange = (
+  range: UndoGuardRange,
+  change: DocChange,
+): UndoGuardRange | null => {
+  // Strict intersection: an edit exactly at a guard boundary (e.g. the user
+  // typing the suppressed space right after the restored text, or deleting it)
+  // must NOT drop the guard.
+  if (change.from < range.to && change.oldTo > range.from) {
+    return null;
+  }
+  // Change fully before the guard: shift the guard by the length delta.
+  if (change.oldTo <= range.from) {
+    const delta = change.newTo - change.oldTo;
+    return { from: range.from + delta, to: range.to + delta };
+  }
+  // Change fully after the guard: positions are unaffected.
+  return range;
+};
+
+// Detect history/remote transactions that may arrive as a whole-document
+// replace step: prosemirror-history undo/redo, or any yjs remote-origin change
+// (isChangeOrigin is the canonical predicate already used across the app).
+const isHistoryOrRemoteTransaction = (tr: Transaction): boolean =>
+  !!tr.getMeta(HISTORY_META) || isChangeOrigin(tr);
+
+export const CustomTypography = Typography.extend({
+  addProseMirrorPlugins() {
+    return [
+      ...(this.parent?.() ?? []),
+      new Plugin({
+        key: undoGuardKey,
+        state: {
+          init: () => null,
+          apply(tr, prev, oldState, newState): UndoGuardRange | null {
+            if (tr.docChanged && isHistoryOrRemoteTransaction(tr)) {
+              const change = findChangedRange(oldState, newState);
+              if (change == null) {
+                // Attribute-only or otherwise content-neutral change: keep the
+                // guard.
+                return prev;
+              }
+              // Arm the guard only when the LOCAL user's undo/redo REPLACED text
+              // (deleted + inserted) — the signature of reverting an input-rule
+              // substitution. Pure insertions/deletions and remote peer edits
+              // must not arm it.
+              if (
+                isUndoRedoTransaction(tr) &&
+                change.oldTo > change.from &&
+                change.newTo > change.from
+              ) {
+                return { from: change.from, to: change.newTo };
+              }
+              // Non-arming history/remote change: map the existing guard through
+              // the real diff instead of the (whole-document) step map.
+              if (!prev) {
+                return null;
+              }
+              return mapRangeThroughChange(prev, change);
+            }
+            if (!prev) {
+              return null;
+            }
+            if (!tr.docChanged) {
+              return prev;
+            }
+            // Ordinary local edit: minimal step maps are accurate and cheap.
+            let range: UndoGuardRange | null = prev;
+            for (const stepMap of tr.mapping.maps) {
+              const { from: rangeFrom, to: rangeTo } = range;
+              let touched = false;
+              stepMap.forEach((fromA, toA) => {
+                if (fromA < rangeTo && toA > rangeFrom) {
+                  touched = true;
+                }
+              });
+              if (touched) {
+                range = null;
+                break;
+              }
+              range = {
+                from: stepMap.map(rangeFrom, 1),
+                to: stepMap.map(rangeTo, -1),
+              };
+            }
+            return range && range.to > range.from ? range : null;
+          },
+        },
+      }),
+    ];
+  },
+
+  addInputRules() {
+    // Wrap every typography rule: skip it when its match overlaps the text
+    // just restored by undo, so an undone substitution is not re-applied.
+    return (this.parent?.() ?? []).map(
+      (rule) =>
+        new InputRule({
+          find: rule.find,
+          undoable: rule.undoable,
+          handler: (props) => {
+            const guard = undoGuardKey.getState(props.state);
+            if (
+              guard &&
+              props.range.from < guard.to &&
+              props.range.to > guard.from
+            ) {
+              // Returning null skips this rule and lets the typed character
+              // be inserted as plain text.
+              return null;
+            }
+            return rule.handler(props);
+          },
+        }),
+    );
+  },
+});

apps/client/src/features/editor/extensions/extensions.ts

@@ -6,7 +6,7 @@ import { TaskList, TaskItem } from "@tiptap/extension-list";
 import { Placeholder, CharacterCount, UndoRedo } from "@tiptap/extensions";
 import { Superscript } from "@tiptap/extension-superscript";
 import SubScript from "@tiptap/extension-subscript";
-import { Typography } from "@tiptap/extension-typography";
+import { CustomTypography } from "./custom-typography";
 import { TextStyle } from "@tiptap/extension-text-style";
 import { Color } from "@tiptap/extension-color";
 import { Youtube } from "@tiptap/extension-youtube";
@@ -245,7 +245,9 @@ export const mainExtensions = [
       return ReactMarkViewRenderer(SpoilerView);
     },
   }),
-  Typography,
+  // Typography with an undo guard: does not re-apply a substitution the user
+  // just undid (e.g. Ctrl+Z on "1/2" -> "½" followed by another space).
+  CustomTypography,
   TrailingNode,
   GlobalDragHandle.configure({
     customNodes: ["transclusionSource", "transclusionReference", "pageEmbed"],

apps/client/src/features/editor/extensions/markdown-clipboard.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { normalizeTableColumnWidths } from "./markdown-clipboard";
+import { htmlToMarkdown } from "@docmost/editor-ext";
+import {
+  normalizeTableColumnWidths,
+  classifyClipboardSelection,
+} from "./markdown-clipboard";
 
 // normalizeTableColumnWidths mutates a DOM subtree (jsdom provides document).
 function root(html: string): HTMLElement {
@@ -124,3 +128,171 @@ describe("normalizeTableColumnWidths", () => {
     ).toEqual([null, null]);
   });
 });
+
+describe("classifyClipboardSelection", () => {
+  it("serializes a list of 2+ items as markdown", () => {
+    expect(
+      classifyClipboardSelection([{ name: "bulletList", childCount: 2 }]),
+    ).toEqual({ asMarkdown: true, wrapBareRows: false });
+  });
+
+  it("leaves a single-item list as plain text", () => {
+    expect(
+      classifyClipboardSelection([{ name: "bulletList", childCount: 1 }]),
+    ).toEqual({ asMarkdown: false, wrapBareRows: false });
+  });
+
+  it("serializes a whole table without wrapping bare rows", () => {
+    expect(
+      classifyClipboardSelection([{ name: "table", childCount: 3 }]),
+    ).toEqual({ asMarkdown: true, wrapBareRows: false });
+  });
+
+  it("serializes a partial cell selection (bare rows) and flags wrapping", () => {
+    expect(
+      classifyClipboardSelection([
+        { name: "tableRow", childCount: 2 },
+        { name: "tableRow", childCount: 2 },
+      ]),
+    ).toEqual({ asMarkdown: true, wrapBareRows: true });
+  });
+
+  it("leaves plain paragraphs as plain text", () => {
+    expect(
+      classifyClipboardSelection([{ name: "paragraph", childCount: 1 }]),
+    ).toEqual({ asMarkdown: false, wrapBareRows: false });
+  });
+
+  it("does not wrap when rows are mixed with other block types", () => {
+    expect(
+      classifyClipboardSelection([
+        { name: "tableRow", childCount: 2 },
+        { name: "paragraph", childCount: 1 },
+      ]),
+    ).toEqual({ asMarkdown: false, wrapBareRows: false });
+  });
+});
+
+// Output-level tests for the table clipboard regression: copying a table must
+// yield a real GFM pipe table, NOT one-value-per-line concatenated cells.
+// These exercise the actual markdown produced by htmlToMarkdown (the same
+// serializer step the clipboardTextSerializer runs), so they pin the OUTPUT
+// shape that the classifier-flag tests above do not cover.
+describe("table clipboard markdown output (htmlToMarkdown)", () => {
+  // Trim each line and drop blanks so structural assertions are whitespace-robust.
+  function lines(md: string): string[] {
+    return md
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+  }
+
+  // A GFM separator row like "| --- | --- |" (any number of columns), tolerant
+  // of the padding turndown emits.
+  function isSeparatorRow(line: string): boolean {
+    const compact = line.replace(/\s+/g, "");
+    return /^\|(?:-{3,}\|)+$/.test(compact);
+  }
+
+  // Split a pipe-delimited row into trimmed cell values.
+  function cells(line: string): string[] {
+    return line
+      .replace(/^\|/, "")
+      .replace(/\|$/, "")
+      .split("|")
+      .map((c) => c.trim());
+  }
+
+  it("serializes a header-less partial cell selection (bare rows) as a valid GFM pipe table", () => {
+    // Mirror the serializer's `wrapBareRows` branch exactly: bare <tr> nodes are
+    // wrapped in <table><tbody> and htmlToMarkdown(div.innerHTML) is called.
+    // See markdown-clipboard.ts clipboardTextSerializer:
+    //   const table = document.createElement("table");
+    //   const tbody = document.createElement("tbody");
+    //   tbody.appendChild(fragment); table.appendChild(tbody);
+    //   div.appendChild(table);
+    //   return htmlToMarkdown(div.innerHTML);
+    const div = document.createElement("div");
+    const table = document.createElement("table");
+    const tbody = document.createElement("tbody");
+    for (const [c1, c2] of [
+      ["a", "b"],
+      ["c", "d"],
+    ]) {
+      const tr = document.createElement("tr");
+      const td1 = document.createElement("td");
+      td1.textContent = c1;
+      const td2 = document.createElement("td");
+      td2.textContent = c2;
+      tr.appendChild(td1);
+      tr.appendChild(td2);
+      tbody.appendChild(tr);
+    }
+    table.appendChild(tbody);
+    div.appendChild(table);
+
+    const md = htmlToMarkdown(div.innerHTML);
+    const ls = lines(md);
+
+    // Valid GFM: a header/data separator row is present (an empty header is
+    // synthesized by the GFM turndown plugin for a header-less table — fine).
+    expect(ls.some(isSeparatorRow)).toBe(true);
+    // NOT the old broken "one value per line" shape: every line is pipe-delimited
+    // and no line is a bare cell value on its own.
+    expect(ls.every((l) => l.includes("|"))).toBe(true);
+    expect(md).not.toMatch(/^\s*(a|b|c|d)\s*$/m);
+    // The cell values land in real pipe-delimited data rows.
+    const dataRows = ls.filter((l) => !isSeparatorRow(l)).map(cells);
+    expect(dataRows).toContainEqual(["a", "b"]);
+    expect(dataRows).toContainEqual(["c", "d"]);
+  });
+
+  it("serializes a whole table with a header row as a proper GFM table (headline regression)", () => {
+    // Mirror the serializer's non-wrap branch: the full <table> node is appended
+    // directly (div.appendChild(fragment)) and htmlToMarkdown(div.innerHTML) runs.
+    const div = document.createElement("div");
+    const table = document.createElement("table");
+
+    const thead = document.createElement("thead");
+    const headerRow = document.createElement("tr");
+    for (const h of ["Name", "Age"]) {
+      const th = document.createElement("th");
+      th.textContent = h;
+      headerRow.appendChild(th);
+    }
+    thead.appendChild(headerRow);
+    table.appendChild(thead);
+
+    const tbody = document.createElement("tbody");
+    for (const [name, age] of [
+      ["Alice", "30"],
+      ["Bob", "25"],
+    ]) {
+      const tr = document.createElement("tr");
+      const td1 = document.createElement("td");
+      td1.textContent = name;
+      const td2 = document.createElement("td");
+      td2.textContent = age;
+      tr.appendChild(td1);
+      tr.appendChild(td2);
+      tbody.appendChild(tr);
+    }
+    table.appendChild(tbody);
+    div.appendChild(table);
+
+    const md = htmlToMarkdown(div.innerHTML);
+    const ls = lines(md);
+
+    // Proper GFM structure: separator row + all rows pipe-delimited.
+    expect(ls.some(isSeparatorRow)).toBe(true);
+    expect(ls.every((l) => l.includes("|"))).toBe(true);
+
+    const rows = ls.filter((l) => !isSeparatorRow(l)).map(cells);
+    // Header row comes first, followed by both data rows.
+    expect(rows[0]).toEqual(["Name", "Age"]);
+    expect(rows).toContainEqual(["Alice", "30"]);
+    expect(rows).toContainEqual(["Bob", "25"]);
+    // Headline regression: the table is NOT concatenated one-value-per-line.
+    expect(md).not.toMatch(/^\s*(Name|Age|Alice|Bob|30|25)\s*$/m);
+  });
+});

apps/client/src/features/editor/extensions/markdown-clipboard.ts

@@ -27,24 +27,36 @@ export const MarkdownClipboard = Extension.create({
         key: new PluginKey("markdownClipboard"),
         props: {
           clipboardTextSerializer: (slice) => {
-            const listTypes = ["bulletList", "orderedList", "taskList"];
-            let topLevelCount = 0;
-            let hasList = false;
+            const topLevelNodes: { name: string; childCount: number }[] = [];
             slice.content.forEach((node) => {
-              if (listTypes.includes(node.type.name)) {
-                hasList = true;
-                topLevelCount += node.childCount;
-              } else {
-                topLevelCount++;
-              }
+              topLevelNodes.push({
+                name: node.type.name,
+                childCount: node.childCount,
+              });
             });
 
-            if (!hasList || topLevelCount < 2) return null;
+            const { asMarkdown, wrapBareRows } =
+              classifyClipboardSelection(topLevelNodes);
+            if (!asMarkdown) return null;
 
             const div = document.createElement("div");
             const serializer = DOMSerializer.fromSchema(this.editor.schema);
             const fragment = serializer.serializeFragment(slice.content);
-            div.appendChild(fragment);
+
+            if (wrapBareRows) {
+              // A partial table cell-selection serializes to bare <tr> nodes
+              // (prosemirror-tables returns the whole `table` node only when the
+              // entire table is selected). Bare <tr> would be foster-parented
+              // away by the HTML parser inside htmlToMarkdown, so wrap them in
+              // <table><tbody> first for the GFM turndown rule to detect them.
+              const table = document.createElement("table");
+              const tbody = document.createElement("tbody");
+              tbody.appendChild(fragment);
+              table.appendChild(tbody);
+              div.appendChild(table);
+            } else {
+              div.appendChild(fragment);
+            }
             return htmlToMarkdown(div.innerHTML);
           },
           handlePaste: (view, event, slice) => {
@@ -153,6 +165,55 @@ export const MarkdownClipboard = Extension.create({
   },
 });
 
+/**
+ * Decide whether a copied slice's plain-text clipboard payload should be
+ * serialized as Markdown (instead of ProseMirror's default text serializer,
+ * which joins block leaves with newlines — the "one value per line" bug for
+ * tables).
+ *
+ * Serialize as Markdown for structured content:
+ *  - lists with 2+ total items (a single copied bullet stays literal text);
+ *  - a whole table (top-level `table` node);
+ *  - a partial table cell-selection, which prosemirror-tables copies as bare
+ *    `tableRow` nodes (only a full-table selection yields a `table` node).
+ *
+ * `wrapBareRows` flags the bare-rows case so the caller wraps the serialized
+ * <tr> nodes in <table><tbody> before the HTML->Markdown step. Plain paragraphs
+ * return asMarkdown=false so a simple text copy stays literal, and internal
+ * copy/paste keeps using the richer text/html clipboard payload.
+ */
+export function classifyClipboardSelection(
+  nodes: { name: string; childCount: number }[],
+): { asMarkdown: boolean; wrapBareRows: boolean } {
+  const listTypes = ["bulletList", "orderedList", "taskList"];
+  let topLevelCount = 0;
+  let hasList = false;
+  let hasTable = false;
+  let tableRowCount = 0;
+  let nonRowCount = 0;
+
+  for (const node of nodes) {
+    if (listTypes.includes(node.name)) {
+      hasList = true;
+      topLevelCount += node.childCount;
+      nonRowCount++;
+    } else {
+      if (node.name === "table") hasTable = true;
+      if (node.name === "tableRow") tableRowCount++;
+      else nonRowCount++;
+      topLevelCount++;
+    }
+  }
+
+  // Bare tableRow nodes at the top level only occur for a partial cell
+  // selection; a slice never mixes bare rows with other block types, so
+  // "every top-level node is a row" is a safe signal to wrap-and-serialize.
+  const wrapBareRows = tableRowCount > 0 && nonRowCount === 0;
+  const asMarkdown =
+    (hasList && topLevelCount >= 2) || hasTable || wrapBareRows;
+  return { asMarkdown, wrapBareRows };
+}
+
 /**
  * Reorder/dedup the footnotes of a SELF-CONTAINED pasted markdown block to the
  * canonical invariant (the live footnoteSyncPlugin never reorders an existing

apps/client/src/features/editor/hooks/use-scroll-position.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { renderHook, act } from "@testing-library/react";
-import { useScrollPosition } from "./use-scroll-position";
+import { useScrollPosition, hasSavedReadingPosition } from "./use-scroll-position";
 
 const KEY_PREFIX = "gitmost:scroll-position:";
 
@@ -100,7 +100,7 @@ describe("useScrollPosition", () => {
     expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
   });
 
-  it("(a3) restores at most once per mount even if called again", () => {
+  it("(a3) is idempotent: re-asserting the same target does not scroll again", () => {
     vi.useFakeTimers();
     window.sessionStorage.setItem(`${KEY_PREFIX}once`, "500");
     setScrollHeight(2000); // tall enough to restore synchronously
@@ -111,8 +111,12 @@ describe("useScrollPosition", () => {
     });
     expect(window.scrollTo).toHaveBeenCalledTimes(1);
 
+    // Simulate the browser now being at the restored position.
+    setScrollY(500);
+
     // A second call (e.g. the wiring effect re-running on [showStatic, editor,
-    // restoreScrollPosition]) must NOT scroll again and yank the reader.
+    // restoreScrollPosition]) must NOT scroll again: the redundancy guard sees
+    // the window is already at the target and does nothing.
     act(() => {
       result.current.restoreScrollPosition();
     });
@@ -162,6 +166,84 @@ describe("useScrollPosition", () => {
     expect(window.scrollTo).not.toHaveBeenCalled();
   });
 
+  it("(g) does not restore if the reader scrolled (wheel) before restore fires", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}g1`, "500");
+    setScrollHeight(2000); // tall enough to restore synchronously
+
+    const { result } = renderHook(() => useScrollPosition("g1"));
+
+    // The reader shows scroll intent before restore is triggered.
+    act(() => {
+      window.dispatchEvent(new Event("wheel"));
+    });
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+
+    expect(window.scrollTo).not.toHaveBeenCalled();
+  });
+
+  it("(h) aborts an in-flight restore poll when the reader scrolls", () => {
+    vi.useFakeTimers();
+    window.sessionStorage.setItem(`${KEY_PREFIX}h1`, "500");
+    setInnerHeight(800);
+    setScrollHeight(100); // maxScroll = -700: target not reachable yet, so it polls.
+
+    const { result } = renderHook(() => useScrollPosition("h1"));
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled(); // still polling
+
+    // The reader takes over mid-poll: this cancels the in-flight poll.
+    act(() => {
+      window.dispatchEvent(new Event("wheel"));
+    });
+
+    // Content of the page grows tall enough and time passes: the cancelled poll
+    // must NOT resurrect and yank the reader.
+    setScrollHeight(2000);
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled();
+  });
+
+  it("(i) a non-scroll keydown does NOT abort restore", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}i1`, "500");
+    setScrollHeight(2000); // tall enough to restore synchronously
+
+    const { result } = renderHook(() => useScrollPosition("i1"));
+
+    // A non-scroll key (e.g. typing, a shortcut) must NOT count as scroll intent.
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent("keydown", { key: "a" }));
+    });
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+
+    // Restore still happens: the innocuous keypress did not disable it.
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
+  });
+
+  it("(j) a scroll keydown (Space) DOES abort restore", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}j1`, "500");
+    setScrollHeight(2000); // tall enough to restore synchronously
+
+    const { result } = renderHook(() => useScrollPosition("j1"));
+
+    // Space scrolls the page: this is real scroll intent and must abort restore.
+    act(() => {
+      window.dispatchEvent(new KeyboardEvent("keydown", { key: " " }));
+    });
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+
+    expect(window.scrollTo).not.toHaveBeenCalled();
+  });
+
   it("(c) does nothing when nothing is saved or the saved value is <= 0", () => {
     // Nothing saved.
     const a = renderHook(() => useScrollPosition("nope"));
@@ -221,6 +303,55 @@ describe("useScrollPosition", () => {
     expect(window.scrollTo).toHaveBeenCalledWith({ top: 200, behavior: "auto" });
   });
 
+  it("(k) shares ONE timeout budget across re-triggers (does not restart the clock)", () => {
+    // The static->live editor swap re-invokes restore. The shared budget
+    // (restoreStartRef) must measure the MAX_RESTORE_WAIT_MS (5000) deadline
+    // from the FIRST trigger, not restart it on every re-trigger. This pins
+    // the `if (restoreStartRef.current === null)` guard: a mutant that resets
+    // `restoreStartRef.current = Date.now()` on every trigger would push the
+    // deadline out to t=8000 (3000 + 5000) and fail the t=5000 assertion below.
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+    window.sessionStorage.setItem(`${KEY_PREFIX}k1`, "5000");
+    setInnerHeight(800);
+    setScrollHeight(1000); // maxScroll = 200, never reaches 5000 -> it polls.
+
+    const { result } = renderHook(() => useScrollPosition("k1"));
+
+    // First trigger at t=0: starts the shared budget and begins polling.
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled();
+
+    // Advance to t=3000 (still polling: content short, not yet timed out).
+    act(() => {
+      vi.advanceTimersByTime(3000);
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled();
+
+    // Second trigger at t=3000 (the swap re-assert). Under the real code the
+    // budget is shared, so `start` stays 0; under the reset-mutant it becomes 3000.
+    act(() => {
+      result.current.restoreScrollPosition();
+    });
+
+    // At t=4900 the FIRST budget has not yet elapsed (4900 - 0 < 5000): no clamp.
+    act(() => {
+      vi.advanceTimersByTime(1900);
+    });
+    expect(window.scrollTo).not.toHaveBeenCalled();
+
+    // At t=5000 the shared budget (measured from t=0) times out and clamps to the
+    // furthest reachable position (maxScroll = 200). The reset-mutant, measuring
+    // from t=3000, would still be waiting (5000 - 3000 = 2000 < 5000) and would
+    // NOT have scrolled here -> this assertion fails against that mutant.
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 200, behavior: "auto" });
+  });
+
   it("(e) never throws when storage access throws", () => {
     const err = new Error("storage denied");
     vi.spyOn(window.sessionStorage, "getItem").mockImplementation(() => {
@@ -241,3 +372,23 @@ describe("useScrollPosition", () => {
     }).not.toThrow();
   });
 });
+
+describe("hasSavedReadingPosition", () => {
+  beforeEach(() => {
+    window.sessionStorage.clear();
+  });
+
+  it("returns false when nothing is saved for the page", () => {
+    expect(hasSavedReadingPosition("none")).toBe(false);
+  });
+
+  it("returns false when the saved value is 0 (page stays at the top)", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}zero`, "0");
+    expect(hasSavedReadingPosition("zero")).toBe(false);
+  });
+
+  it("returns true when a positive position is saved", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}deep`, "500");
+    expect(hasSavedReadingPosition("deep")).toBe(true);
+  });
+});

apps/client/src/features/editor/hooks/use-scroll-position.ts

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
+import type { Editor } from "@tiptap/react";
 
 // Throttle interval for persisting the scroll position while the user reads.
 const SAVE_THROTTLE_MS = 250;
@@ -13,6 +14,18 @@ const RESTORE_POLL_MS = 100;
 // "remember where I was reading" feature (self-limiting, no cross-tab leak).
 const STORAGE_PREFIX = "gitmost:scroll-position:";
 
+// Keys that scroll the window. Only these count as scroll intent for keydown;
+// other keys (shortcuts, modifiers, typing) must NOT disable scroll restore.
+const SCROLL_KEYS = new Set([
+  "ArrowUp",
+  "ArrowDown",
+  "PageUp",
+  "PageDown",
+  "Home",
+  "End",
+  " ", // Space (and Shift+Space) scroll the page
+]);
+
 function storageKey(pageId: string): string {
   return `${STORAGE_PREFIX}${pageId}`;
 }
@@ -44,36 +57,56 @@ function writeStorage(pageId: string, scrollY: number): void {
   }
 }
 
+/**
+ * Whether a positive reading position is saved for this page — i.e. the page
+ * will be scrolled away from the top on load. Used by the title editor to avoid
+ * auto-focusing (and thus placing the caret in) the now-off-screen title.
+ * Returns false when nothing is saved or storage is unavailable.
+ */
+export function hasSavedReadingPosition(pageId: string): boolean {
+  const y = readStorage(pageId);
+  return typeof y === "number" && y > 0;
+}
+
 /**
  * Persists and restores the window scroll position per page so a reader keeps
  * their place across a reload (F5) or reopening the document.
  *
- * Returns `restoreScrollPosition`, which the page editor calls once the live
- * (non-static) content is laid out. The two scroll mechanisms are mutually
- * exclusive: if the URL has a `#hash` anchor, the existing anchor-scroll logic
- * wins and restore is a no-op.
+ * Returns `restoreScrollPosition`, which the page editor calls from two triggers
+ * (early, while the static/cached content is laid out, and again after the
+ * static->live editor swap); it is idempotent, so re-asserting the same target is
+ * a no-op. The two scroll mechanisms are mutually exclusive: if the URL has a
+ * `#hash` anchor, the existing anchor-scroll logic wins and restore is a no-op.
  */
 export function useScrollPosition(pageId: string): {
   restoreScrollPosition: () => void;
 } {
   // CONTRACT: this hook assumes PageEditor REMOUNTS per page — page.tsx renders
   // `<MemoizedFullEditor key={page.id} ...>`, so switching pages creates a fresh
-  // hook instance with fresh refs. These refs latch per-mount and are NOT reset
-  // when `pageId` changes in place (only the effect re-runs on [pageId]). If that
-  // `key={page.id}` is ever removed, restore would silently break on the 2nd page
-  // (refs would hold the first page's target / already-restored flag) — in that
-  // case the refs must be reset on a pageId change.
+  // hook instance with fresh refs. Restore is idempotent and interaction-gated
+  // (not single-shot): it may be called from several triggers and re-asserts the
+  // SAME captured target, which is a no-op once the window is already positioned.
+  // The per-mount refs that latch are `initialTargetRef` (the captured target)
+  // and `userInteractedRef` (the reader has taken over scrolling). They are NOT
+  // reset when `pageId` changes in place (only the effect re-runs on [pageId]).
+  // If that `key={page.id}` is ever removed, restore would silently break on the
+  // 2nd page (refs would hold the first page's target / interaction flag) — in
+  // that case the refs must be reset on a pageId change.
   //
   // The target Y captured synchronously at mount, BEFORE any scroll/visibility
   // handler can overwrite the stored value with a fresh 0 (the page starts
   // scrolled to top on load). `null` means "not yet captured".
   const initialTargetRef = useRef<number | null>(null);
-  // Guards so restore runs at most once per page mount.
-  const hasRestoredRef = useRef(false);
+  // Set once the reader shows unambiguous scroll intent; restore must never yank
+  // a reader who has already started scrolling.
+  const userInteractedRef = useRef(false);
   // Holds the in-flight restore poll timer so the cleanup can cancel it: without
   // this, a fast SPA navigation away mid-poll would let the old page's poll fire
   // window.scrollTo against the NEW page's document (visible wrong-page scroll).
   const pollTimerRef = useRef<number | null>(null);
+  // Timestamp of the FIRST restore attempt so re-triggers (e.g. the static→live
+  // editor swap) share ONE bounded timeout budget instead of restarting it.
+  const restoreStartRef = useRef<number | null>(null);
 
   // Capture the previously-saved value synchronously during render, before the
   // effect below registers handlers that would persist the current (0) scrollY.
@@ -114,14 +147,43 @@ export function useScrollPosition(pageId: string): {
       }
     };
 
+    // User scroll-intent signals. wheel and touch are unconditional scroll
+    // intent; keydown is filtered to actual scroll keys only (SCROLL_KEYS) so
+    // shortcuts, lone modifiers, and typing do not abort restore. Our own
+    // window.scrollTo does NOT emit these, so restore can never self-abort via
+    // them. Once the reader shows intent we mark it and cancel any in-flight
+    // restore poll so restore can never yank them back. (Scrollbar-drag via
+    // pointer is an accepted small gap — it is not covered here.)
+    const onUserIntent = (event: Event) => {
+      // wheel/touchstart are unambiguous scroll intent; for keydown, only real
+      // scroll keys count — a shortcut or typing must not abort restore.
+      if (
+        event.type === "keydown" &&
+        !SCROLL_KEYS.has((event as KeyboardEvent).key)
+      ) {
+        return;
+      }
+      userInteractedRef.current = true;
+      if (pollTimerRef.current !== null) {
+        window.clearTimeout(pollTimerRef.current);
+        pollTimerRef.current = null;
+      }
+    };
+
     window.addEventListener("scroll", onScroll, { passive: true });
     window.addEventListener("pagehide", onPageHide);
     document.addEventListener("visibilitychange", onVisibilityChange);
+    window.addEventListener("wheel", onUserIntent, { passive: true });
+    window.addEventListener("touchstart", onUserIntent, { passive: true });
+    window.addEventListener("keydown", onUserIntent);
 
     return () => {
       window.removeEventListener("scroll", onScroll);
       window.removeEventListener("pagehide", onPageHide);
       document.removeEventListener("visibilitychange", onVisibilityChange);
+      window.removeEventListener("wheel", onUserIntent);
+      window.removeEventListener("touchstart", onUserIntent);
+      window.removeEventListener("keydown", onUserIntent);
       if (throttleTimer !== null) {
         window.clearTimeout(throttleTimer);
         throttleTimer = null;
@@ -137,9 +199,8 @@ export function useScrollPosition(pageId: string): {
   }, [pageId]);
 
   const restoreScrollPosition = useCallback(() => {
-    // Run at most once per page mount.
-    if (hasRestoredRef.current) return;
-    hasRestoredRef.current = true;
+    // The reader took over — never yank them back.
+    if (userInteractedRef.current) return;
 
     // Anchor priority: a `#hash` in the URL is handled by useEditorScroll.
     if (window.location.hash) return;
@@ -148,9 +209,26 @@ export function useScrollPosition(pageId: string): {
     // Nothing meaningful to restore to.
     if (targetY <= 0) return;
 
-    const start = Date.now();
+    // Cancel any in-flight poll before (re)starting, so overlapping triggers can
+    // never run two concurrent polls against the same target.
+    if (pollTimerRef.current !== null) {
+      window.clearTimeout(pollTimerRef.current);
+      pollTimerRef.current = null;
+    }
+
+    // Share one timeout budget across re-triggers instead of restarting it.
+    if (restoreStartRef.current === null) {
+      restoreStartRef.current = Date.now();
+    }
+    const start = restoreStartRef.current;
 
     const tryRestore = () => {
+      // Bail mid-poll if the reader started scrolling while we were waiting.
+      if (userInteractedRef.current) {
+        pollTimerRef.current = null;
+        return;
+      }
+
       const maxScroll =
         document.documentElement.scrollHeight - window.innerHeight;
       const timedOut = Date.now() - start >= MAX_RESTORE_WAIT_MS;
@@ -158,10 +236,12 @@ export function useScrollPosition(pageId: string): {
       // Restore once the content is tall enough to reach the target, or bail out
       // after the timeout and scroll as far as currently possible.
       if (maxScroll >= targetY || timedOut) {
-        window.scrollTo({
-          top: Math.min(targetY, Math.max(maxScroll, 0)),
-          behavior: "auto",
-        });
+        const top = Math.min(targetY, Math.max(maxScroll, 0));
+        // Redundancy guard: re-asserting the SAME target when already positioned
+        // is a no-op, so this hook can be called from multiple triggers safely.
+        if (Math.abs(window.scrollY - top) > 1) {
+          window.scrollTo({ top, behavior: "auto" });
+        }
         pollTimerRef.current = null;
         return;
       }
@@ -175,3 +255,37 @@ export function useScrollPosition(pageId: string): {
 
   return { restoreScrollPosition };
 }
+
+/**
+ * Wires `useScrollPosition` to the page editor's static->live swap lifecycle.
+ *
+ * Extracted from PageEditor so the exact restore triggers (their deps and the
+ * post-swap `&& editor` guard) are directly unit-testable rather than mirrored.
+ * Behaviour is unchanged: `restoreScrollPosition` is idempotent, so re-asserting
+ * the same target from either trigger is a no-op.
+ *
+ * @param pageId      the page whose scroll position is persisted/restored.
+ * @param editor      the tiptap editor instance, or `null` until it is ready.
+ * @param showStatic  whether the static (cached) content is still shown.
+ */
+export function useScrollRestoreOnSwap(
+  pageId: string,
+  editor: Editor | null,
+  showStatic: boolean,
+): void {
+  const { restoreScrollPosition } = useScrollPosition(pageId);
+
+  // Restore as early as the static (cached) content is laid out, before paint,
+  // so the reader's position is applied without a visible jump. Aborts itself if
+  // the reader has already started scrolling (handled inside the hook).
+  useLayoutEffect(() => {
+    restoreScrollPosition();
+  }, [restoreScrollPosition]);
+
+  // Re-assert once after the static -> live editor swap in case the swap reset
+  // the window scroll. Idempotent: a no-op when the position is already correct,
+  // and a no-op after the reader has interacted.
+  useLayoutEffect(() => {
+    if (!showStatic && editor) restoreScrollPosition();
+  }, [showStatic, editor, restoreScrollPosition]);
+}

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/hooks/use-title-autofocus.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useTitleAutofocus } from "./use-title-autofocus";
+
+const KEY_PREFIX = "gitmost:scroll-position:";
+
+function fakeEditor(overrides = {}) {
+  return { isInitialized: true, commands: { focus: vi.fn() }, ...overrides } as any;
+}
+
+describe("useTitleAutofocus", () => {
+  beforeEach(() => {
+    window.sessionStorage.clear();
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("skips auto-focus when a saved reading position exists", () => {
+    window.sessionStorage.setItem(`${KEY_PREFIX}saved`, "500");
+    const editor = fakeEditor();
+    renderHook(() => useTitleAutofocus(editor, "saved"));
+    act(() => vi.advanceTimersByTime(300));
+    expect(editor.commands.focus).not.toHaveBeenCalled();
+  });
+
+  it("auto-focuses a new page (no saved position) with scrollIntoView: false", () => {
+    const editor = fakeEditor();
+    renderHook(() => useTitleAutofocus(editor, "fresh"));
+    act(() => vi.advanceTimersByTime(300));
+    expect(editor.commands.focus).toHaveBeenCalledWith("end", { scrollIntoView: false });
+  });
+
+  it("does not focus before initialization", () => {
+    const editor = fakeEditor({ isInitialized: false });
+    renderHook(() => useTitleAutofocus(editor, "fresh2"));
+    act(() => vi.advanceTimersByTime(300));
+    expect(editor.commands.focus).not.toHaveBeenCalled();
+  });
+
+  it("cancels the pending focus on unmount", () => {
+    const editor = fakeEditor();
+    const { unmount } = renderHook(() => useTitleAutofocus(editor, "fresh3"));
+    unmount();
+    act(() => vi.advanceTimersByTime(300));
+    expect(editor.commands.focus).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/hooks/use-title-autofocus.ts

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from "react";
+import type { Editor } from "@tiptap/react";
+import { hasSavedReadingPosition } from "./use-scroll-position";
+
+// Delay before auto-focusing the title on load — guards a tiptap init race
+// ("Cannot access view['hasFocus']" if focused too early).
+const TITLE_AUTOFOCUS_DELAY_MS = 300;
+
+/**
+ * Auto-focus the page title shortly after mount — UNLESS a saved reading position
+ * will be restored (then the viewport scrolls away from the top, and focusing the
+ * top-of-page title would drop the caret off-screen). When it does focus, it uses
+ * `{ scrollIntoView: false }` so placing the caret never moves the viewport
+ * (tiptap's focus scrolls the focused node into view by default, which otherwise
+ * yanks the window to the top and fights scroll-position restoration).
+ *
+ * Extracted from TitleEditor so this exact decision is unit-testable.
+ *
+ * CONTRACT: relies on TitleEditor remounting per page (page.tsx renders
+ * `<MemoizedFullEditor key={page.id}>`), so `hasSavedScrollRef` is captured fresh
+ * per page. It is read synchronously on first render, before any scroll-save
+ * handler can clobber the stored value to 0 — matching `useScrollPosition`'s own
+ * synchronous capture of `initialTargetRef`.
+ */
+export function useTitleAutofocus(
+  titleEditor: Editor | null,
+  pageId: string,
+): void {
+  const hasSavedScrollRef = useRef<boolean | null>(null);
+  if (hasSavedScrollRef.current === null) {
+    hasSavedScrollRef.current = hasSavedReadingPosition(pageId);
+  }
+
+  useEffect(() => {
+    if (hasSavedScrollRef.current) return;
+    const timer = setTimeout(() => {
+      // guard against "Cannot access view['hasFocus']" before init
+      if (!titleEditor?.isInitialized) return;
+      titleEditor?.commands?.focus("end", { scrollIntoView: false });
+    }, TITLE_AUTOFOCUS_DELAY_MS);
+    // Clear the pending focus if the editor changes or the component unmounts
+    // (also fixes the previously-uncancelled timer).
+    return () => clearTimeout(timer);
+  }, [titleEditor]);
+}

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

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act } from "@testing-library/react";
+import type { Editor } from "@tiptap/react";
+import { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
+
+const KEY_PREFIX = "gitmost:scroll-position:";
+
+// NOTE ON SCOPE (F2 — reviewer-approved lighter variant).
+//
+// The real UX wiring lives in the exported `useScrollRestoreOnSwap` hook (two
+// useLayoutEffects around useScrollPosition), which PageEditor calls with the
+// same signature. A FULL PageEditor component test is impractical here and has no
+// precedent in this client: PageEditor directly constructs a
+// HocuspocusProviderWebsocket + IndexeddbPersistence, a tiptap `useEditor` with
+// collab extensions, reads jotai atoms, react-router params, the shared
+// `queryClient` from main.tsx, i18n, and mounts ~12 editor menu children. Worse,
+// the static->live swap (`showStatic` -> false) is gated on
+// `isCollabSynced(status, isLocalSynced && isRemoteSynced)`, which can only flip
+// by driving the mocked collab provider's async sync callbacks. The heaviest
+// component-test precedent in the repo (comment-hover-preview.test.tsx) mounts a
+// single leaf component with ONE mocked query; nothing mounts a feature root of
+// this weight. Reproducing all of that would test the mocks, not the wiring.
+//
+// So this file tests the REAL `useScrollRestoreOnSwap` hook — the exact code
+// PageEditor imports and calls — driving its `showStatic`/`editor` inputs the way
+// the swap does. Because it exercises the real hook (not a copy), dropping the
+// `&& editor` guard or changing the effect deps makes these tests fail; they
+// guard the production code directly (verified: removing `&& editor` reddens the
+// first test).
+//
+// Both tests observe the real effect via `window.scrollTo`. The stubbed
+// `window.scrollTo` never mutates `window.scrollY`, and the target is left
+// unreached, so every restore invocation that passes the guard yields exactly one
+// `scrollTo` call — making the call count a faithful proxy for restore invocations.
+
+function setScrollY(value: number): void {
+  Object.defineProperty(window, "scrollY", { configurable: true, value });
+}
+function setScrollHeight(value: number): void {
+  Object.defineProperty(document.documentElement, "scrollHeight", {
+    configurable: true,
+    value,
+  });
+}
+function setInnerHeight(value: number): void {
+  Object.defineProperty(window, "innerHeight", { configurable: true, value });
+}
+
+// Minimal stand-in for the tiptap editor: the hook only truthiness-checks it.
+const fakeEditor = { id: "editor" } as unknown as Editor;
+
+// Thin host that calls the REAL hook so a rerender drives showStatic/editor
+// exactly like the page-editor swap does.
+function Host({
+  pageId,
+  showStatic,
+  editor,
+}: {
+  pageId: string;
+  showStatic: boolean;
+  editor: Editor | null;
+}) {
+  useScrollRestoreOnSwap(pageId, editor, showStatic);
+  return null;
+}
+
+describe("PageEditor scroll-restore wiring (useScrollRestoreOnSwap)", () => {
+  beforeEach(() => {
+    window.sessionStorage.clear();
+    setScrollY(0);
+    setScrollHeight(0);
+    setInnerHeight(800);
+    window.scrollTo = vi.fn();
+    window.location.hash = "";
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+    window.location.hash = "";
+  });
+
+  it("re-invokes restore after the swap, with the [showStatic, editor] deps/guard", () => {
+    // Target is immediately reachable, so each restore that passes the guard
+    // scrolls synchronously. `window.scrollY` stays 0 (stubbed scrollTo never
+    // updates it), so scrollTo is called once per effective restore — a proxy for
+    // the restore invocation count.
+    window.sessionStorage.setItem(`${KEY_PREFIX}guard`, "500");
+    setInnerHeight(800);
+    setScrollHeight(2000); // maxScroll = 1200 >= 500: reachable, no polling.
+
+    // Pre-swap: static content shown, live editor not ready. Only the early
+    // pre-paint restore fires; the post-swap effect's guard (!showStatic) blocks it.
+    const { rerender } = render(
+      <Host pageId="guard" showStatic={true} editor={null} />,
+    );
+    expect(window.scrollTo).toHaveBeenCalledTimes(1);
+
+    // Collab reports synced (showStatic flips false) but the editor is not ready
+    // yet: the swap effect re-runs (deps [showStatic, editor] changed) but the
+    // `&& editor` guard must keep it a no-op. The early effect does NOT re-fire
+    // (its dep [restoreScrollPosition] is a stable useCallback([])).
+    // (Pins the guard: dropping `&& editor` would restore against a null editor,
+    // producing a 2nd scrollTo and failing this expectation.)
+    rerender(<Host pageId="guard" showStatic={false} editor={null} />);
+    expect(window.scrollTo).toHaveBeenCalledTimes(1);
+
+    // The static -> live swap completes (showStatic false AND editor present): the
+    // post-swap effect re-asserts the restore exactly once more, driven solely by
+    // the [showStatic, editor] deps changing.
+    rerender(<Host pageId="guard" showStatic={false} editor={fakeEditor} />);
+    expect(window.scrollTo).toHaveBeenCalledTimes(2);
+  });
+
+  it("the post-swap re-assert drives a REAL restore (window.scrollTo) via the hook", () => {
+    // End-to-end through the real useScrollPosition (inside the hook): the swap
+    // re-invocation is the CAUSE of the scroll (nothing scrolls before it).
+    vi.useFakeTimers();
+    window.sessionStorage.setItem(`${KEY_PREFIX}peg`, "500");
+    setInnerHeight(800);
+    setScrollHeight(100); // maxScroll = -700: target not reachable yet -> polls.
+
+    // Pre-swap: the early restore runs but content is too short, so it starts
+    // polling (a pending timer) without scrolling. We never advance timers, so the
+    // early poll cannot fire on its own — isolating the swap as the sole cause.
+    const { rerender } = render(
+      <Host pageId="peg" showStatic={true} editor={null} />,
+    );
+    expect(window.scrollTo).not.toHaveBeenCalled();
+
+    // The live content is now laid out tall enough to reach the target.
+    setScrollHeight(2000); // maxScroll = 1200 >= 500
+
+    // The static -> live swap: the post-swap useLayoutEffect re-invokes the real
+    // hook, whose synchronous tryRestore now reaches the target and scrolls.
+    act(() => {
+      rerender(<Host pageId="peg" showStatic={false} editor={fakeEditor} />);
+    });
+    expect(window.scrollTo).toHaveBeenCalledWith({ top: 500, behavior: "auto" });
+  });
+});

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";
@@ -78,7 +79,8 @@ import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { jwtDecode } from "jwt-decode";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
-import { useScrollPosition } from "./hooks/use-scroll-position";
+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,12 +141,12 @@ 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],
   );
   const { handleScrollTo } = useEditorScroll({ canScroll });
-  const { restoreScrollPosition } = useScrollPosition(pageId);
   // Providers only created once per pageId
   const providersRef = useRef<{
     local: IndexeddbPersistence;
@@ -450,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) {
@@ -472,25 +491,55 @@ 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]);
 
-  // Restore the saved reading position once the live content is laid out.
-  useEffect(() => {
-    if (!showStatic && editor) restoreScrollPosition();
-  }, [showStatic, editor, restoreScrollPosition]);
+  // Restore the reader's scroll position across the static -> live editor swap.
+  // The wiring (early pre-paint restore + post-swap re-assert) lives in the hook
+  // so its triggers/guard are directly unit-testable.
+  useScrollRestoreOnSwap(pageId, editor, showStatic);
 
   return (
     <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
@@ -578,6 +627,7 @@ export default function PageEditor({
           ></div>
         </div>
       )}
+      </div>
         </PageEmbedAncestryProvider>
       </PageEmbedLookupProvider>
     </TransclusionLookupProvider>

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

@@ -28,6 +28,7 @@ import localEmitter from "@/lib/local-emitter.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { platformModifierKey } from "@/lib";
+import { useTitleAutofocus } from "@/features/editor/hooks/use-title-autofocus";
 
 export interface TitleEditorProps {
   pageId: string;
@@ -167,13 +168,7 @@ export function TitleEditor({
     }
   }, [pageId, title, titleEditor]);
 
-  useEffect(() => {
-    setTimeout(() => {
-      // guard against Cannot access view['hasFocus'] error
-      if (!titleEditor?.isInitialized) return;
-      titleEditor?.commands?.focus("end");
-    }, 300);
-  }, [titleEditor]);
+  useTitleAutofocus(titleEditor, pageId);
 
   useEffect(() => {
     return () => {

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

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

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

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

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

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

apps/client/src/features/page/tree/atoms/open-tree-nodes-atom.ts

@@ -13,20 +13,30 @@ export type OpenMap = Record<string, boolean>;
 // `OpenMap | Promise<OpenMap>` and break the functional-updater setter below).
 const openTreeNodesStorage = createJSONStorage<OpenMap>(() => localStorage);
 
+// Single source of truth for the open-map localStorage key prefix. Exported so
+// the logout cache sweep (tree-data-atom.ts) removes keys by the SAME prefix
+// used to write them — a rename here can never silently desync the cleanup.
+export const OPEN_TREE_NODES_KEY_PREFIX = "openTreeNodes:";
+
 // One persisted open/closed map per (workspace, user). Scoping the localStorage
 // key prevents accounts that share a browser origin from leaking tree state.
 // `getOnInit: true` reads localStorage synchronously at atom init (not on mount),
 // so the first render already has the saved state — no collapse-then-expand
 // flicker on reload, and writes never run against an un-hydrated empty map.
 const openTreeNodesFamily = atomFamily((scopeKey: string) =>
-  atomWithStorage<OpenMap>(`openTreeNodes:${scopeKey}`, {}, openTreeNodesStorage, {
-    getOnInit: true,
-  }),
+  atomWithStorage<OpenMap>(
+    `${OPEN_TREE_NODES_KEY_PREFIX}${scopeKey}`,
+    {},
+    openTreeNodesStorage,
+    { getOnInit: true },
+  ),
 );
 
 // Resolve the storage scope from the current user. Fall back to "anon" for the
 // workspace/user parts when nothing is loaded yet (logged out / first paint).
-const scopeKeyAtom = atom((get) => {
+// Shared by the open-map atom below and the persisted tree-data atom
+// (tree-data-atom.ts) so both caches are scoped identically.
+export const scopeKeyAtom = atom((get) => {
   const currentUser = get(currentUserAtom);
   const workspaceId = currentUser?.workspace?.id ?? "anon";
   const userId = currentUser?.user?.id ?? "anon";

apps/client/src/features/page/tree/atoms/tree-data-atom.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { SpaceTreeNode } from "@/features/page/tree/types";
+import type { ICurrentUser } from "@/features/user/types/user.types";
+
+// The persisted tree-data atom hydrates from localStorage ONCE, at family-atom
+// creation (`getOnInit: true`). To exercise hydration deterministically each
+// test imports a FRESH module instance (fresh atomFamily) after seeding the
+// storage stub from vitest.setup.ts. jotai itself is externalized by vitest, so
+// `createStore` can stay a static import — atoms are plain objects and any
+// store works with any module instance.
+import { createStore } from "jotai";
+
+// Storage key for the default scope: no currentUser -> "anon:anon" (see
+// scopeKeyAtom in open-tree-nodes-atom.ts) with the `v1` cache-shape version.
+const ANON_KEY = "treeData:v1:anon:anon";
+const DEBOUNCE_MS = 500;
+
+async function freshImport() {
+  vi.resetModules();
+  const treeDataModule = await import("./tree-data-atom");
+  const userModule = await import(
+    "@/features/user/atoms/current-user-atom"
+  );
+  return {
+    treeDataAtom: treeDataModule.treeDataAtom,
+    flushPendingTreeDataWrites: treeDataModule.flushPendingTreeDataWrites,
+    clearPersistedTreeCaches: treeDataModule.clearPersistedTreeCaches,
+    currentUserAtom: userModule.currentUserAtom,
+  };
+}
+
+function node(id: string): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id,
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId: null as unknown as string,
+    hasChildren: false,
+    children: [],
+  };
+}
+
+// Every persisted tree key currently in storage — asserting on the whole
+// prefix (not one known key) catches writes that resurrect under ANY scope.
+function persistedTreeDataKeys(): string[] {
+  const keys: string[] = [];
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (key !== null && key.startsWith("treeData:v1:")) keys.push(key);
+  }
+  return keys;
+}
+
+function currentUser(workspaceId: string, userId: string): ICurrentUser {
+  return {
+    user: { id: userId },
+    workspace: { id: workspaceId },
+  } as unknown as ICurrentUser;
+}
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("treeDataAtom (localStorage-persisted)", () => {
+  it("reads [] from a fresh store with empty storage", async () => {
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    expect(store.get(treeDataAtom)).toEqual([]);
+  });
+
+  it("persists through the debounced setItem and hydrates a fresh module back", async () => {
+    vi.useFakeTimers();
+    const setItemSpy = vi.spyOn(localStorage, "setItem");
+
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    store.set(treeDataAtom, [node("a")]);
+    // Second write inside the debounce window — must coalesce into ONE flush
+    // carrying only the latest value.
+    vi.advanceTimersByTime(DEBOUNCE_MS / 2);
+    store.set(treeDataAtom, [node("a"), node("b")]);
+
+    // Nothing flushed yet: the write is trailing-debounced.
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+
+    expect(setItemSpy).toHaveBeenCalledTimes(1);
+    expect(JSON.parse(localStorage.getItem(ANON_KEY)!)).toEqual([
+      node("a"),
+      node("b"),
+    ]);
+
+    // A fresh module (fresh atom family -> getOnInit re-reads storage) and a
+    // fresh store hydrate the persisted tree back — the reload scenario.
+    const second = await freshImport();
+    const store2 = createStore();
+    expect(store2.get(second.treeDataAtom)).toEqual([node("a"), node("b")]);
+  });
+
+  it("reads [] (without throwing) when storage holds corrupted JSON", async () => {
+    localStorage.setItem(ANON_KEY, "{definitely not JSON!!!");
+
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    expect(store.get(treeDataAtom)).toEqual([]);
+  });
+
+  it("reads [] when storage holds valid JSON of a non-array shape", async () => {
+    localStorage.setItem(ANON_KEY, JSON.stringify({ id: "not-a-tree" }));
+
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    expect(store.get(treeDataAtom)).toEqual([]);
+  });
+
+  it("supports functional-updater writes", async () => {
+    const { treeDataAtom } = await freshImport();
+    const store = createStore();
+
+    store.set(treeDataAtom, [node("a")]);
+    store.set(treeDataAtom, (prev) => [...prev, node("b")]);
+
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["a", "b"]);
+  });
+
+  it("isolates trees between (workspace, user) scopes", async () => {
+    const { treeDataAtom, currentUserAtom } = await freshImport();
+    const store = createStore();
+
+    store.set(currentUserAtom, currentUser("w1", "u1"));
+    store.set(treeDataAtom, [node("a")]);
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["a"]);
+
+    // Another account on the same browser origin must NOT see u1's tree.
+    store.set(currentUserAtom, currentUser("w2", "u2"));
+    expect(store.get(treeDataAtom)).toEqual([]);
+
+    store.set(treeDataAtom, [node("b")]);
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["b"]);
+
+    // Switching back resolves the original scope's tree untouched.
+    store.set(currentUserAtom, currentUser("w1", "u1"));
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["a"]);
+  });
+
+  it("clearPersistedTreeCaches removes all tree keys and discards pending writes", async () => {
+    vi.useFakeTimers();
+
+    // Stale caches across scopes plus an UNRELATED key that must survive.
+    localStorage.setItem("treeData:v1:a:b", JSON.stringify([node("stale")]));
+    localStorage.setItem("openTreeNodes:a:b", JSON.stringify({ p1: true }));
+    localStorage.setItem("currentUser", JSON.stringify({ user: { id: "b" } }));
+
+    const { treeDataAtom, clearPersistedTreeCaches } = await freshImport();
+    const store = createStore();
+
+    // Queue a debounced write (not flushed yet) for the anon scope.
+    store.set(treeDataAtom, [node("pending")]);
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+
+    clearPersistedTreeCaches();
+
+    // Both prefixed caches are swept; the unrelated key is untouched.
+    expect(localStorage.getItem("treeData:v1:a:b")).toBeNull();
+    expect(localStorage.getItem("openTreeNodes:a:b")).toBeNull();
+    expect(localStorage.getItem("currentUser")).toBe(
+      JSON.stringify({ user: { id: "b" } }),
+    );
+
+    // The queued write was DISCARDED, not merely delayed: the debounce timer
+    // firing later must not resurrect a tree key after logout.
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+  });
+
+  it("clearPersistedTreeCaches discards queued writes even when flushed DIRECTLY", async () => {
+    vi.useFakeTimers();
+
+    const { treeDataAtom, clearPersistedTreeCaches, flushPendingTreeDataWrites } =
+      await freshImport();
+    const store = createStore();
+
+    // Queue a debounced write, then clear. Calling the flush directly (not via
+    // the debounce timer) isolates the pending-queue discard from the timer
+    // cancel: if the queue survived, this flush would resurrect the key even
+    // though the timer never fired.
+    store.set(treeDataAtom, [node("pending")]);
+    clearPersistedTreeCaches();
+    flushPendingTreeDataWrites();
+
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+    expect(persistedTreeDataKeys()).toEqual([]);
+  });
+
+  it("skips persisting a tree over the size cap and warns exactly once", async () => {
+    vi.useFakeTimers();
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const setItemSpy = vi.spyOn(localStorage, "setItem");
+
+    const { treeDataAtom, flushPendingTreeDataWrites } = await freshImport();
+    const store = createStore();
+
+    // One node whose name alone serializes to > MAX_SERIALIZED_LENGTH (~4M).
+    const huge = node("big");
+    huge.name = "x".repeat(4_000_001);
+
+    store.set(treeDataAtom, [huge]);
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+
+    // The oversized serialization is skipped: the key is never written.
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+    expect(setItemSpy).not.toHaveBeenCalled();
+
+    // Editing the still-oversized tree fires another debounced write, but the
+    // "too large" warn is gated by the once-flag — no per-tick console spam.
+    store.set(treeDataAtom, [huge, node("big2")]);
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+    flushPendingTreeDataWrites();
+
+    expect(localStorage.getItem(ANON_KEY)).toBeNull();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      "[tree] cached tree too large to persist; skipping",
+      ANON_KEY,
+    );
+  });
+
+  it("disables persistence after clearPersistedTreeCaches: NEW writes never reach storage", async () => {
+    vi.useFakeTimers();
+
+    const { treeDataAtom, clearPersistedTreeCaches, flushPendingTreeDataWrites } =
+      await freshImport();
+    const store = createStore();
+
+    clearPersistedTreeCaches();
+
+    // The resurrection scenario: a websocket tree event lands while `await
+    // logout()` is still in flight, AFTER the sweep. The write must not be
+    // queued, must not arm a new debounce timer, and must not survive the
+    // beforeunload flush fired by the logout redirect.
+    store.set(treeDataAtom, [node("late")]);
+
+    vi.advanceTimersByTime(DEBOUNCE_MS + 100);
+    flushPendingTreeDataWrites(); // what the beforeunload handler runs
+
+    expect(persistedTreeDataKeys()).toEqual([]);
+
+    // Only PERSISTENCE is disabled: the in-memory atom keeps working, so the
+    // UI stays intact during the brief pre-redirect window.
+    expect(store.get(treeDataAtom).map((n) => n.id)).toEqual(["late"]);
+  });
+});

apps/client/src/features/page/tree/atoms/tree-data-atom.ts

@@ -1,8 +1,206 @@
 import { atom } from "jotai";
+import { atomFamily, atomWithStorage } from "jotai/utils";
 import { SpaceTreeNode } from "@/features/page/tree/types";
 import { appendNodeChildren } from "../utils";
+import {
+  OPEN_TREE_NODES_KEY_PREFIX,
+  scopeKeyAtom,
+} from "./open-tree-nodes-atom";
 
-export const treeDataAtom = atom<SpaceTreeNode[]>([]);
+// The sidebar tree is persisted to localStorage so a page reload can paint the
+// last-known tree IMMEDIATELY (no blank sidebar while the root query runs) and
+// then reconcile with the server in the background. localStorage is a BOOT
+// CACHE only — the in-memory atom stays the source of truth while the app runs.
+
+// Trailing-debounce machinery for the localStorage writes. The tree is
+// rewritten on every lazy load / drag / socket event; serializing a large tree
+// on each update would burn CPU and thrash the storage quota, so writes are
+// coalesced (~500 ms per burst) and only the latest value per key is flushed.
+const WRITE_DEBOUNCE_MS = 500;
+
+// Single source of truth for the tree-cache localStorage key prefix. The `v1`
+// segment versions the cached node shape (bump it when SpaceTreeNode changes
+// incompatibly). Shared by the storage key construction below AND the logout
+// sweep in clearPersistedTreeCaches() so the two can never drift apart.
+export const TREE_DATA_KEY_PREFIX = "treeData:v1:";
+
+// Size guard: skip persisting trees whose JSON exceeds ~4M chars. localStorage
+// quota is typically ~5 MB per origin; a huge tree must not evict everything
+// else or spam QuotaExceededError on every debounce tick.
+const MAX_SERIALIZED_LENGTH = 4_000_000;
+
+const pendingWrites = new Map<string, SpaceTreeNode[]>();
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+let writeFailureWarned = false;
+
+// Persistence kill-switch, armed by clearPersistedTreeCaches(). Once set, the
+// debounced setItem and the flush become no-ops so nothing can be written back
+// to localStorage AFTER the logout sweep: a websocket tree event landing while
+// `await logout()` is still in flight would otherwise re-queue a write that
+// the `beforeunload` flush (fired by the redirect) silently resurrects.
+// Intentionally never reset: every caller of clearPersistedTreeCaches()
+// immediately navigates away with a full page load
+// (window.location.replace/href), so this module instance is torn down anyway.
+// Only PERSISTENCE stops — the in-memory atoms keep working, so the UI stays
+// intact during the brief pre-redirect window.
+let persistenceDisabled = false;
+
+function writeNow(key: string, value: SpaceTreeNode[]): void {
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized.length > MAX_SERIALIZED_LENGTH) {
+      // Warn ONCE, like the quota branch below: a >4M-char tree re-serializes on
+      // every ~500ms debounce tick while it's edited, so an un-gated warn would
+      // spam the console on each flush.
+      if (!writeFailureWarned) {
+        writeFailureWarned = true;
+        console.warn("[tree] cached tree too large to persist; skipping", key);
+      }
+      return;
+    }
+    localStorage.setItem(key, serialized);
+  } catch (err) {
+    // QuotaExceededError, private mode, jsdom shims without working storage…
+    // The cache is best-effort: warn once, keep the in-memory tree working.
+    if (!writeFailureWarned) {
+      writeFailureWarned = true;
+      console.warn("[tree] failed to persist tree cache", err);
+    }
+  }
+}
+
+// Exported so tests can force the debounced write synchronously; production
+// code must never need it (the beforeunload hook below covers reloads).
+export function flushPendingTreeDataWrites(): void {
+  if (flushTimer !== null) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  if (persistenceDisabled) {
+    // Belt-and-braces: after logout nothing may reach localStorage, even via
+    // the beforeunload flush racing the redirect. Drop anything queued.
+    pendingWrites.clear();
+    return;
+  }
+  for (const [key, value] of pendingWrites) {
+    writeNow(key, value);
+  }
+  pendingWrites.clear();
+}
+
+// Logout hygiene: the tree cache stores PAGE TITLES, so leaving it behind
+// would keep them readable in localStorage on a shared machine after logout.
+// Sweep by key prefix (not just the current scope) so stale scopes — old
+// users, the `anon:anon` fallback — are purged too. Pending debounced writes
+// are DISCARDED first (not flushed): a queued write firing after the sweep
+// would silently resurrect a removed key.
+export function clearPersistedTreeCaches(): void {
+  // Disable persistence FIRST so no write can be queued (or flushed) between
+  // the sweep below and the full-page navigation every caller performs next.
+  persistenceDisabled = true;
+  if (flushTimer !== null) {
+    clearTimeout(flushTimer);
+    flushTimer = null;
+  }
+  pendingWrites.clear();
+  try {
+    // Collect matching keys BEFORE removing: deleting while iterating
+    // `localStorage.key(i)` shifts the indices and skips entries.
+    const keysToRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (
+        key !== null &&
+        (key.startsWith(TREE_DATA_KEY_PREFIX) ||
+          key.startsWith(OPEN_TREE_NODES_KEY_PREFIX))
+      ) {
+        keysToRemove.push(key);
+      }
+    }
+    for (const key of keysToRemove) {
+      localStorage.removeItem(key);
+    }
+  } catch {
+    // Best-effort: disabled storage / jsdom shims must never break logout.
+  }
+}
+
+// Flush the pending debounced write on unload so a reload right after a tree
+// change doesn't lose the newest state (the debounce would otherwise eat it).
+if (
+  typeof window !== "undefined" &&
+  typeof window.addEventListener === "function"
+) {
+  window.addEventListener("beforeunload", flushPendingTreeDataWrites);
+}
+
+// Custom sync storage for the tree cache. Deliberately NO `subscribe` key:
+// cross-tab sync would REPLACE this tab's tree wholesale and clobber in-flight
+// lazy loads; websockets already keep every open tab live. Each tab keeps its
+// own in-memory tree — localStorage only seeds the next boot.
+const treeDataStorage = {
+  getItem: (key: string, initialValue: SpaceTreeNode[]): SpaceTreeNode[] => {
+    // Defensive: jsdom test shims may lack methods, stored JSON may be
+    // corrupted or of a wrong shape. Any failure falls back to the empty tree.
+    try {
+      const raw = localStorage.getItem(key);
+      if (raw === null) return initialValue;
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? (parsed as SpaceTreeNode[]) : initialValue;
+    } catch {
+      return initialValue;
+    }
+  },
+  setItem: (key: string, newValue: SpaceTreeNode[]): void => {
+    // After logout the cache must stay purged: neither queue the write nor arm
+    // a new flush timer (see persistenceDisabled above). The in-memory atom
+    // value is unaffected — only the localStorage mirror is frozen.
+    if (persistenceDisabled) return;
+    pendingWrites.set(key, newValue);
+    if (flushTimer !== null) clearTimeout(flushTimer);
+    flushTimer = setTimeout(flushPendingTreeDataWrites, WRITE_DEBOUNCE_MS);
+  },
+  removeItem: (key: string): void => {
+    pendingWrites.delete(key);
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      /* best-effort cache — ignore */
+    }
+  },
+};
+
+// One persisted tree per (workspace, user) — same scoping rationale as the
+// open-map atom (accounts sharing a browser origin must not leak trees).
+// `getOnInit: true` reads localStorage synchronously at atom init, so the very
+// first render already has the cached tree — no blank-then-jump sidebar.
+const treeDataFamily = atomFamily((scopeKey: string) =>
+  atomWithStorage<SpaceTreeNode[]>(
+    `${TREE_DATA_KEY_PREFIX}${scopeKey}`,
+    [],
+    treeDataStorage,
+    { getOnInit: true },
+  ),
+);
+
+// Public facade — same read value (SpaceTreeNode[]) and same setter shape
+// (value OR functional updater) as the previous in-memory atom, transparently
+// routed to the persisted tree of the current workspace/user.
+export const treeDataAtom = atom(
+  (get) => get(treeDataFamily(get(scopeKeyAtom))),
+  (
+    get,
+    set,
+    update: SpaceTreeNode[] | ((prev: SpaceTreeNode[]) => SpaceTreeNode[]),
+  ) => {
+    const target = treeDataFamily(get(scopeKeyAtom));
+    const next =
+      typeof update === "function"
+        ? (update as (prev: SpaceTreeNode[]) => SpaceTreeNode[])(get(target))
+        : update;
+    set(target, next);
+  },
+);
 
 // Atom
 export const appendNodeChildrenAtom = atom(

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

@@ -0,0 +1,222 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createRef } from "react";
+import { render, act, waitFor, cleanup } from "@testing-library/react";
+
+// --- Mocks for the heavy / networked module graph ---------------------------
+// Same isolation strategy as space-tree.expand-all.test.tsx: everything that
+// would otherwise need a real server / router / DnD stack is mocked. Here we
+// additionally CAPTURE the DocTree props (onToggle + data) so the test can
+// drive a lazy-load expand exactly as a row click would, and we control
+// fetchAllAncestorChildren to assert the fresh fetch happens.
+
+const fetchAllAncestorChildrenMock = vi.fn();
+
+// Holder mutated by the DocTree stub each render so the test can read the
+// latest tree it was handed and invoke its onToggle callback.
+const docTree: {
+  onToggle?: (id: string, isOpen: boolean) => void | Promise<void>;
+  data: unknown[];
+} = { data: [] };
+
+vi.mock("@/features/page/services/page-service.ts", () => ({
+  getSpaceTree: vi.fn(),
+  getPageBreadcrumbs: vi.fn(),
+}));
+
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  // No root pages and no further pages — the server data-load effect stays
+  // inert (isDataLoaded never flips), so refreshOpenBranches never runs and the
+  // test exercises ONLY the boot-prune + handleToggle lazy-load path against
+  // the hydrated cache we seed into the atom below.
+  useGetRootSidebarPagesQuery: () => ({
+    data: undefined,
+    hasNextPage: false,
+    fetchNextPage: vi.fn(),
+    isFetching: false,
+  }),
+  usePageQuery: () => ({ data: undefined }),
+  fetchAllAncestorChildren: (...args: unknown[]) =>
+    fetchAllAncestorChildrenMock(...args),
+}));
+
+vi.mock("@/features/page/tree/hooks/use-tree-mutation.ts", () => ({
+  useTreeMutation: () => ({ handleMove: vi.fn() }),
+}));
+
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("react-router-dom", () => ({
+  useParams: () => ({ pageSlug: undefined }),
+}));
+
+vi.mock("@/lib", () => ({
+  extractPageSlugId: () => undefined,
+}));
+
+vi.mock("@/lib/config.ts", () => ({
+  isCompactPageTreeEnabled: () => false,
+}));
+
+// Capture the props DocTree is rendered with instead of rendering anything.
+vi.mock("./doc-tree", () => ({
+  DocTree: (props: { onToggle: (id: string, isOpen: boolean) => void; data: unknown[] }) => {
+    docTree.onToggle = props.onToggle;
+    docTree.data = props.data;
+    return null;
+  },
+  ROW_HEIGHT_COMPACT: 28,
+  ROW_HEIGHT_STANDARD: 32,
+}));
+vi.mock("./space-tree-row", () => ({
+  SpaceTreeRow: () => null,
+}));
+
+vi.mock("@mantine/core", () => ({
+  Text: ({ children }: { children?: unknown }) => children ?? null,
+}));
+
+// In-memory open-map (the real one is localStorage-backed and crashes under the
+// jsdom shim). Empty at start of each test -> every branch is COLLAPSED, which
+// is exactly the state we need to prove the boot-prune. `scopeKeyAtom` is
+// re-exported because the persisted tree-data atom resolves its scope through it.
+vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
+  const { atom } = await import("jotai");
+  type OpenMap = Record<string, boolean>;
+  const base = atom<OpenMap>({});
+  const openTreeNodesAtom = atom(
+    (get) => get(base),
+    (get, set, update: OpenMap | ((prev: OpenMap) => OpenMap)) => {
+      const next =
+        typeof update === "function"
+          ? (update as (prev: OpenMap) => OpenMap)(get(base))
+          : update;
+      set(base, next);
+    },
+  );
+  const scopeKeyAtom = atom(() => "test-workspace:test-user");
+  return { openTreeNodesAtom, scopeKeyAtom };
+});
+
+import SpaceTree, { SpaceTreeApi } from "./space-tree";
+import {
+  treeDataAtom,
+  flushPendingTreeDataWrites,
+} from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { createStore, Provider } from "jotai";
+import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
+
+// The scopeKeyAtom mock resolves to this fixed scope, so the persisted
+// tree-data atom hydrates from exactly this localStorage key at mount
+// (getOnInit + atomWithStorage's onMount both read it).
+const CACHE_KEY = "treeData:v1:test-workspace:test-user";
+
+function child(
+  id: string,
+  parentPageId: string,
+  hasChildren = false,
+): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id,
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId,
+    hasChildren,
+    children: [],
+  };
+}
+
+// A hydrated boot cache: a COLLAPSED branch (not in the open-map) that still
+// carries a stale cached child — the exact shape a previous session left behind
+// after the branch was expanded then collapsed then persisted.
+function cachedTreeWithCollapsedBranch(): SpaceTreeNode[] {
+  return [
+    {
+      id: "branch",
+      slugId: "slug-branch",
+      name: "branch",
+      position: "a0",
+      spaceId: "space-1",
+      parentPageId: null as unknown as string,
+      hasChildren: true,
+      children: [child("stale", "branch")],
+    },
+  ];
+}
+
+beforeEach(() => {
+  fetchAllAncestorChildrenMock.mockReset();
+  docTree.onToggle = undefined;
+  docTree.data = [];
+  // Flush any pending debounced write from a previous test before clearing.
+  flushPendingTreeDataWrites();
+  try {
+    localStorage.clear?.();
+  } catch {
+    /* fresh store per test isolates state */
+  }
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("SpaceTree boot-cache prune (#159 #8 stale collapsed children)", () => {
+  it("drops a collapsed cached branch's children on boot and fetches fresh on first expand", async () => {
+    // Server returns FRESH children on the lazy-load: the stale cached child is
+    // gone, a renamed/new one takes its place.
+    fetchAllAncestorChildrenMock.mockResolvedValue([child("fresh", "branch")]);
+
+    // Simulate the localStorage-hydrated boot cache: seed the persisted key
+    // BEFORE mount so the atom hydrates it (store.set would be clobbered by
+    // atomWithStorage's onMount re-reading storage — this is the real path).
+    localStorage.setItem(
+      CACHE_KEY,
+      JSON.stringify(cachedTreeWithCollapsedBranch()),
+    );
+
+    const store = createStore();
+    const ref = createRef<SpaceTreeApi>();
+    render(
+      <Provider store={store}>
+        <SpaceTree ref={ref} spaceId="space-1" readOnly={false} />
+      </Provider>,
+    );
+
+    // Boot-prune ran at mount: the COLLAPSED branch's cached children were
+    // dropped to the unloaded shape ([]), so the stale child is no longer there.
+    const branchAfterBoot = docTree.data.find(
+      (n) => (n as SpaceTreeNode).id === "branch",
+    ) as SpaceTreeNode;
+    expect(branchAfterBoot.children).toEqual([]);
+    expect(branchAfterBoot.hasChildren).toBe(true);
+
+    // First expand of the collapsed branch after boot must lazy-load fresh
+    // children (before this fix the cached children were kept and the fetch
+    // was skipped, showing stale data).
+    await act(async () => {
+      await docTree.onToggle!("branch", true);
+    });
+
+    expect(fetchAllAncestorChildrenMock).toHaveBeenCalledTimes(1);
+    expect(fetchAllAncestorChildrenMock).toHaveBeenCalledWith({
+      pageId: "branch",
+      spaceId: "space-1",
+    });
+
+    // The fresh children replaced the stale cache in the live tree.
+    await waitFor(() => {
+      const branch = store
+        .get(treeDataAtom)
+        .find((n) => n.id === "branch")!;
+      expect(branch.children.map((c) => c.id)).toEqual(["fresh"]);
+    });
+  });
+});

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

@@ -71,7 +71,8 @@ vi.mock("@mantine/core", () => ({
 // getOnInit), which crashes under jsdom's localStorage shim here. Swap in a
 // plain in-memory atom with the same read value (OpenMap) and the same setter
 // shape (value OR functional updater) so the component's open-state logic runs
-// unchanged while staying inside the test store.
+// unchanged while staying inside the test store. `scopeKeyAtom` is also
+// re-exported (the real module exports it for the persisted tree-data atom).
 vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
   const { atom } = await import("jotai");
   type OpenMap = Record<string, boolean>;
@@ -86,11 +87,17 @@ vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
       set(base, next);
     },
   );
-  return { openTreeNodesAtom };
+  // Fixed scope key: the tree-data atom family resolves through this, so all
+  // tests read/write the same (empty at start of each test) storage key.
+  const scopeKeyAtom = atom(() => "test-workspace:test-user");
+  return { openTreeNodesAtom, scopeKeyAtom };
 });
 
 import SpaceTree, { SpaceTreeApi } from "./space-tree";
-import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import {
+  treeDataAtom,
+  flushPendingTreeDataWrites,
+} from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { openTreeNodesAtom } from "@/features/page/tree/atoms/open-tree-nodes-atom.ts";
 import { createStore, Provider } from "jotai";
 import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
@@ -134,6 +141,10 @@ function renderTree(store: ReturnType<typeof createStore>) {
 beforeEach(() => {
   getSpaceTreeMock.mockReset();
   notificationsShowMock.mockReset();
+  // The tree-data atom persists via a ~500 ms trailing debounce; flush it NOW
+  // (cancelling the timer) so a previous test's pending write can't land in
+  // storage mid-test after the clear below.
+  flushPendingTreeDataWrites();
   // jsdom's localStorage shim here lacks `clear`; guard it. Each test uses a
   // fresh jotai store anyway, so cross-test open-state never leaks.
   try {

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

@@ -30,6 +30,7 @@ import {
   openBranches,
   closeIds,
   loadedOpenBranchIds,
+  pruneCollapsedChildren,
 } from "@/features/page/tree/utils/utils.ts";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import { treeModel } from "@/features/page/tree/model/tree-model";
@@ -199,45 +200,81 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
   const openIdsRef = useRef(openIds);
   openIdsRef.current = openIds;
 
-  // Reconnect refresh (#159 #8): on a socket reconnect, re-fetch and reconcile
-  // the children of every currently-open, already-loaded branch of THIS space,
+  // Boot-cache hygiene (#159 #8): the localStorage-hydrated tree carries the
+  // children of every branch ever expanded, including ones now COLLAPSED. Their
+  // first expand would skip the lazy-load and render stale children (a
+  // rename/move/delete missed while offline). Drop the cached children of every
+  // COLLAPSED branch ONCE at mount so its first expand fetches fresh via
+  // handleToggle — exactly as it did before the tree was cached. OPEN branches
+  // keep their children and are refreshed by refreshOpenBranches instead, so
+  // this runs before any expand and never double-fetches an open branch.
+  const prunedBootCacheRef = useRef(false);
+  useEffect(() => {
+    if (prunedBootCacheRef.current) return;
+    prunedBootCacheRef.current = true;
+    setData((prev) => pruneCollapsedChildren(prev, openIdsRef.current));
+  }, [setData]);
+
+  // Re-fetch and reconcile the children of every currently-open, already-loaded
+  // branch of THIS space. Shared by the socket reconnect handler and the
+  // post-load cache refresh below. The ROOT level is reconciled separately by
+  // the root-query refetch + mergeRootTrees; an UNLOADED branch is skipped
+  // (lazy-load fetches it fresh on expand). Reads refs so it always sees the
+  // latest tree/open-state/space without re-creating the callback.
+  const refreshOpenBranches = useCallback(async () => {
+    const effectSpaceId = spaceIdRef.current;
+    const branchIds = loadedOpenBranchIds(
+      dataRef.current.filter((n) => n?.spaceId === effectSpaceId),
+      openIdsRef.current,
+    );
+    if (branchIds.length === 0) return;
+    for (const id of branchIds) {
+      try {
+        // `fresh: true` bypasses the 30-min sidebar-pages cache so the
+        // reconcile sees the server's CURRENT children (handler-order
+        // independent — no reliance on the global reconnect invalidation).
+        const fresh = await fetchAllAncestorChildren(
+          { pageId: id, spaceId: effectSpaceId },
+          { fresh: true },
+        );
+        if (spaceIdRef.current !== effectSpaceId) return; // space switched
+        setData((prev) => treeModel.reconcileChildren(prev, id, fresh));
+      } catch (err) {
+        console.error("[tree] open branch refresh failed", err);
+      }
+    }
+  }, [setData]);
+
+  // Reconnect refresh (#159 #8): on a socket reconnect, refresh open branches
   // so a move/rename/delete that happened INSIDE a loaded branch while events
   // were missed (laptop sleep / wifi gap) is reflected instead of left stale.
-  // The ROOT level is reconciled separately by the root-query refetch +
-  // mergeRootTrees; an UNLOADED branch is skipped (lazy-load fetches it fresh on
-  // expand). No first-connect guard is needed: space-tree usually mounts AFTER
-  // the initial connect, so every `connect` it sees is a reconnect; the rare
+  // No first-connect guard is needed: space-tree usually mounts AFTER the
+  // initial connect, so every `connect` it sees is a reconnect; the rare
   // initial-connect case has an empty tree, so the refresh is a harmless no-op.
   useEffect(() => {
     if (!socket) return;
-    const onConnect = async () => {
-      const effectSpaceId = spaceIdRef.current;
-      const branchIds = loadedOpenBranchIds(
-        dataRef.current.filter((n) => n?.spaceId === effectSpaceId),
-        openIdsRef.current,
-      );
-      if (branchIds.length === 0) return;
-      for (const id of branchIds) {
-        try {
-          // `fresh: true` bypasses the 30-min sidebar-pages cache so the
-          // reconcile sees the server's CURRENT children (handler-order
-          // independent — no reliance on the global reconnect invalidation).
-          const fresh = await fetchAllAncestorChildren(
-            { pageId: id, spaceId: effectSpaceId },
-            { fresh: true },
-          );
-          if (spaceIdRef.current !== effectSpaceId) return; // space switched
-          setData((prev) => treeModel.reconcileChildren(prev, id, fresh));
-        } catch (err) {
-          console.error("[tree] reconnect branch refresh failed", err);
-        }
-      }
+    const onConnect = () => {
+      refreshOpenBranches();
     };
     socket.on("connect", onConnect);
     return () => {
       socket.off("connect", onConnect);
     };
-  }, [socket, setData]);
+  }, [socket, refreshOpenBranches]);
+
+  // Post-load cache refresh: the sidebar paints instantly from the
+  // localStorage-cached tree, so children of open branches may be stale. Once
+  // the server root set has been merged for this space (isDataLoaded flips
+  // true), refresh every open, already-loaded branch ONCE per space per mount.
+  // dataRef.current is already up to date here: refs are assigned during
+  // render, and this effect runs after the merge-triggered re-render commit.
+  const refreshedSpacesRef = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    if (!isDataLoaded) return;
+    if (refreshedSpacesRef.current.has(spaceId)) return;
+    refreshedSpacesRef.current.add(spaceId);
+    refreshOpenBranches();
+  }, [isDataLoaded, spaceId, refreshOpenBranches]);
 
   const handleToggle = useCallback(
     async (id: string, isOpen: boolean) => {
@@ -333,12 +370,17 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
 
   return (
     <div className={classes.treeContainer}>
+      {/* "No pages yet" only after the SERVER confirmed the space is empty —
+          never while just the localStorage cache is empty. */}
       {isDataLoaded && filteredData.length === 0 && (
         <Text size="xs" c="dimmed" py="xs" px="sm">
           {t("No pages yet")}
         </Text>
       )}
-      {isDataLoaded && filteredData.length > 0 && (
+      {/* Cache-first paint: render as soon as ANY data exists (synchronous
+          localStorage hydration) instead of waiting for the server round-trip;
+          the background merge/refresh reconciles it afterwards. */}
+      {filteredData.length > 0 && (
         <DocTree<SpaceTreeNode>
           data={filteredData}
           openIds={openIds}

apps/client/src/features/page/tree/utils/utils.test.ts

@@ -8,6 +8,7 @@ import {
   closeIds,
   mergeRootTrees,
   loadedOpenBranchIds,
+  pruneCollapsedChildren,
   sortPositionKeys,
   pageToTreeNode,
 } from "./utils";
@@ -438,3 +439,62 @@ describe("loadedOpenBranchIds (#159 #8 reconnect refresh targets)", () => {
     expect(ids.sort()).toEqual(["a", "a1"]);
   });
 });
+
+describe("pruneCollapsedChildren", () => {
+  // Signature: pruneCollapsedChildren(tree: SpaceTreeNode[], openIds:
+  // ReadonlySet<string>): SpaceTreeNode[]. Collapsed nodes (id NOT in openIds)
+  // are reset to `children: []` (hasChildren untouched); open nodes keep their
+  // children but are recursed into so a collapsed branch nested under an open
+  // one is still pruned.
+  //
+  // Fixture:
+  //   open "p" (in openIds, hasChildren)
+  //     └─ collapsed "c" (NOT in openIds) with STALE child "g"
+  //   collapsed "t" (NOT in openIds) with child "t1"
+  // Only "p" is open.
+  function fixture() {
+    const grandchild = treeNode("g"); // stale, cached under the collapsed child
+    const collapsedChild = treeNode("c", [grandchild]);
+    const openParent = treeNode("p", [collapsedChild]);
+    const topCollapsed = treeNode("t", [treeNode("t1")]);
+    return { openParent, collapsedChild, topCollapsed };
+  }
+
+  it("keeps an OPEN parent's children and recurses to prune a nested collapsed branch; prunes a top-level collapsed node", () => {
+    const { openParent, topCollapsed } = fixture();
+    const tree = [openParent, topCollapsed];
+    const result = pruneCollapsedChildren(tree, new Set(["p"]));
+
+    // (a) OPEN parent keeps its children (not cleared) and hasChildren stays true.
+    const p = result[0];
+    expect(p.id).toBe("p");
+    expect(p.hasChildren).toBe(true);
+    expect(p.children).toHaveLength(1);
+
+    // (b) The nested COLLAPSED child under the open parent is pruned to
+    // `children: []` by the recursion, with hasChildren preserved. This is the
+    // open-keep + recurse branch that F1's empty-open-set fixture never hits.
+    const c = p.children[0];
+    expect(c.id).toBe("c");
+    expect(c.children).toEqual([]);
+    expect(c.hasChildren).toBe(true);
+
+    // (c) The top-level collapsed node is pruned to `children: []`, hasChildren kept.
+    const t = result[1];
+    expect(t.id).toBe("t");
+    expect(t.children).toEqual([]);
+    expect(t.hasChildren).toBe(true);
+  });
+
+  it("does not mutate the input tree (returns fresh nodes)", () => {
+    const { openParent, collapsedChild, topCollapsed } = fixture();
+    const tree = [openParent, topCollapsed];
+    pruneCollapsedChildren(tree, new Set(["p"]));
+
+    // Originals are untouched: the collapsed child still carries its stale grandchild.
+    expect(collapsedChild.children).toHaveLength(1);
+    expect(collapsedChild.children[0].id).toBe("g");
+    expect(openParent.children[0]).toBe(collapsedChild);
+    expect(topCollapsed.children).toHaveLength(1);
+  });
+});

apps/client/src/features/page/tree/utils/utils.ts

@@ -293,6 +293,41 @@ export function loadedOpenBranchIds(
   return ids;
 }
 
+/**
+ * Boot-cache hygiene (#159 #8): the persisted tree keeps the children of EVERY
+ * branch ever expanded — collapsing a branch never prunes them. So on reload a
+ * COLLAPSED branch hydrates with its old cached children, and `handleToggle`
+ * skips the lazy-load on first expand (children already present) → it shows
+ * STALE children (renamed / moved / deleted while the user was offline) with no
+ * reconcile. `refreshOpenBranches` only refreshes OPEN branches, so collapsed
+ * ones slip through.
+ *
+ * Fix: drop the cached children of every node NOT in the persisted open-set,
+ * resetting it to the canonical UNLOADED shape (`children: []`, `hasChildren`
+ * untouched — see pageToTreeNode). Its first expand then lazy-loads fresh, just
+ * as it did before the tree was cached to localStorage. OPEN branches keep
+ * their children (refreshOpenBranches reconciles those, so they must not be
+ * dropped here) and are recursed into so a collapsed branch nested under an
+ * open one is pruned too.
+ */
+export function pruneCollapsedChildren(
+  tree: SpaceTreeNode[],
+  openIds: ReadonlySet<string>,
+): SpaceTreeNode[] {
+  return tree.map((node) => {
+    const hasLoadedChildren = !!node.children && node.children.length > 0;
+    if (!openIds.has(node.id)) {
+      // Collapsed: drop the whole cached subtree so it reads as unloaded.
+      return hasLoadedChildren ? { ...node, children: [] } : node;
+    }
+    // Open: keep it, but recurse into its children (a nested collapsed branch
+    // must still be pruned).
+    return hasLoadedChildren
+      ? { ...node, children: pruneCollapsedChildren(node.children, openIds) }
+      : node;
+  });
+}
+
 // Collect every node id in the tree (roots, branches, leaves). Used by
 // collapseAll to clear the open-state map for all current-space nodes.
 export function collectAllIds(nodes: SpaceTreeNode[]): string[] {

apps/client/src/lib/api-client.ts

@@ -1,6 +1,7 @@
 import axios, { AxiosInstance } from "axios";
 import APP_ROUTE from "@/lib/app-route.ts";
 import { isCloud } from "@/lib/config.ts";
+import { clearPersistedTreeCaches } from "@/features/page/tree/atoms/tree-data-atom";
 
 const api: AxiosInstance = axios.create({
   baseURL: "/api",
@@ -71,6 +72,12 @@ function redirectToLogin() {
     "/invites",
   ];
   if (!exemptPaths.some((path) => window.location.pathname.startsWith(path))) {
+    // Forced logout (401 / expired session) must purge the persisted sidebar
+    // tree caches too: they contain page titles, and on a shared machine most
+    // sessions end via cookie expiry — not the logout button — so this is the
+    // only cleanup that runs on that path. It also disables further cache
+    // persistence until the full page load below.
+    clearPersistedTreeCaches();
     const redirectTo = window.location.pathname;
     if (redirectTo === APP_ROUTE.HOME) {
       window.location.href = APP_ROUTE.AUTH.LOGIN;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -303,6 +303,11 @@ describe('buildSystemPrompt page-changed note (#274)', () => {
     expect(prompt).toContain(NOTE_MARKER);
     expect(prompt).toContain('-old line');
     expect(prompt).toContain('+new line');
+    // Strengthened note (#274): instructs a fresh re-read via getPage and steers
+    // the agent toward small, targeted edits instead of a full-page overwrite.
+    expect(prompt).toContain('getPage');
+    expect(prompt.toLowerCase()).toContain('targeted');
+    expect(prompt).toContain('editPageText');
     // Inside the safety sandwich: the trailing SAFETY block follows the note.
     expect(prompt.lastIndexOf(SAFETY_MARKER)).toBeGreaterThan(
       prompt.indexOf(NOTE_MARKER),

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

@@ -85,11 +85,17 @@ const INTERRUPT_NOTE =
 const PAGE_CHANGED_NOTE =
   'NOTE: The user edited the open page AFTER your last response in this ' +
   'conversation, so any copy of that page you produced or remember from earlier ' +
-  'is now STALE. The unified diff below shows exactly what changed since you last ' +
-  'spoke (lines starting with "-" were removed, "+" were added) and is the source ' +
-  'of truth. Preserve the user\'s edits: build on the current page, do not revert ' +
-  'or overwrite their changes. If you need the full up-to-date page, re-read it ' +
-  'with the getPage tool before editing.';
+  'is now STALE and must not be reused. Before you edit the page, you MUST first ' +
+  're-read its current content with the getPage tool and base your work on that ' +
+  'live version — never on your earlier copy or on the transcript. The unified ' +
+  'diff below shows exactly what the user changed since you last spoke (lines ' +
+  'starting with "-" were removed, "+" were added) and is the source of truth. ' +
+  'Preserve every one of the user\'s edits: make the smallest change that ' +
+  'satisfies the request using the targeted edit tools (editPageText, patchNode, ' +
+  'insertNode, deleteNode) rather than replacing the whole page, and do not ' +
+  'revert, drop, or overwrite anything the user changed. If a full rewrite is ' +
+  'truly unavoidable, start from the current getPage content and carry over all ' +
+  'of the user\'s edits.';
 
 /**
  * Sanitize a value interpolated into a prompt XML-ish attribute (e.g.

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

@@ -356,6 +356,32 @@ describe('flushAssistant', () => {
     expect(flushed.toolCalls).not.toBeNull();
     expect(flushed.metadata.error).toBe('boom');
   });
+
+  // #274 observability: the page-change diff the agent saw this turn is persisted
+  // to metadata.pageChanged when a non-empty diff was injected, and omitted when
+  // the diff is empty/whitespace or the arg is not supplied.
+  it('persists metadata.pageChanged when a non-empty diff was injected', () => {
+    const f = flushAssistant([], '', 'completed', {
+      pageChanged: { title: 'Doc', diff: '@@ -1 +1 @@\n-old\n+new' },
+    });
+    expect(f.metadata.pageChanged).toEqual({
+      title: 'Doc',
+      diff: '@@ -1 +1 @@\n-old\n+new',
+    });
+  });
+
+  it('omits metadata.pageChanged for an empty/whitespace diff or a missing arg', () => {
+    const whitespace = flushAssistant([], '', 'completed', {
+      pageChanged: { title: 'Doc', diff: '   \n  ' },
+    });
+    expect('pageChanged' in whitespace.metadata).toBe(false);
+
+    const nullArg = flushAssistant([], '', 'completed', { pageChanged: null });
+    expect('pageChanged' in nullArg.metadata).toBe(false);
+
+    const omitted = flushAssistant([], '', 'streaming');
+    expect('pageChanged' in omitted.metadata).toBe(false);
+  });
 });
 
 /**

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

@@ -685,7 +685,7 @@ export class AiChatService implements OnModuleInit {
     // no-op (guarded below) so the turn still streams to the user.
     let assistantId: string | undefined;
     try {
-      const seed = flushAssistant([], '', 'streaming');
+      const seed = flushAssistant([], '', 'streaming', { pageChanged });
       const seeded = await this.aiChatMessageRepo.insert({
         chatId,
         workspaceId: workspace.id,
@@ -720,7 +720,7 @@ export class AiChatService implements OnModuleInit {
         await this.aiChatMessageRepo.update(
           assistantId,
           workspace.id,
-          flushAssistant(capturedSteps, '', 'streaming'),
+          flushAssistant(capturedSteps, '', 'streaming', { pageChanged }),
           { onlyIfStreaming: true },
         );
       } catch (err) {
@@ -860,6 +860,7 @@ export class AiChatService implements OnModuleInit {
               // resolved from the admin-configured provider settings (in
               // closure scope here). Omitted/0 = no limit.
               maxContextTokens: resolved?.chatContextWindow,
+              pageChanged,
             }),
           );
           // Lifecycle: release the external MCP clients leased for this turn.
@@ -911,6 +912,7 @@ export class AiChatService implements OnModuleInit {
           await finalizeAssistant(
             flushAssistant(capturedSteps, inProgressText, 'error', {
               error: errorText,
+              pageChanged,
             }),
           );
           await closeExternalClients();
@@ -940,7 +942,9 @@ export class AiChatService implements OnModuleInit {
               `steps=${steps.length}`,
           );
           await finalizeAssistant(
-            flushAssistant(capturedSteps, inProgressText, 'aborted'),
+            flushAssistant(capturedSteps, inProgressText, 'aborted', {
+              pageChanged,
+            }),
           );
           await closeExternalClients();
           // Advance the page snapshot even on abort (#274): an agent edit that
@@ -1506,6 +1510,7 @@ export function flushAssistant(
     contextTokens?: number;
     maxContextTokens?: number;
     error?: string;
+    pageChanged?: { title: string; diff: string } | null;
   },
 ): AssistantFlush {
   const finished = capturedSteps ?? [];
@@ -1538,6 +1543,15 @@ export function flushAssistant(
   if (extra?.maxContextTokens)
     metadata.maxContextTokens = extra.maxContextTokens;
   if (extra?.error) metadata.error = extra.error;
+  // Persist the page-change diff the agent saw this turn (#274 observability),
+  // so history / the Markdown export can show what the user changed. Only when
+  // a non-empty diff was actually injected into the prompt this turn.
+  if (extra?.pageChanged && extra.pageChanged.diff?.trim().length) {
+    metadata.pageChanged = {
+      title: extra.pageChanged.title,
+      diff: extra.pageChanged.diff,
+    };
+  }
 
   return {
     content: stepsText + trailing,

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

@@ -269,6 +269,168 @@ describe('buildChatMarkdown (server) — structure', () => {
     expect(md).toContain('**⚠️ Error:** 401: Unauthorized');
   });
 
+  // #274 observability: an assistant row whose turn started with a user edit to
+  // the open page carries metadata.pageChanged = { title, diff }; the export
+  // renders the diff the agent saw, before the message body.
+  it('renders the persisted page-change diff block for an assistant row', () => {
+    const md = buildChatMarkdown({
+      title: 'T',
+      chatId: 'c',
+      rows: [
+        row({
+          role: 'assistant',
+          content: 'answer',
+          metadata: {
+            pageChanged: { title: 'Doc', diff: '@@ -1 +1 @@\n-old\n+new' },
+          } as never,
+        }),
+      ],
+    });
+    expect(md).toContain(
+      'The user edited this page before this turn; the diff the agent saw:',
+    );
+    expect(md).toContain('("Doc")');
+    expect(md).toContain('-old');
+    expect(md).toContain('+new');
+    // The diff sits before the message body (chronological: change, then reply).
+    expect(md.indexOf('-old')).toBeLessThan(md.indexOf('answer'));
+  });
+
+  it('does not render the page-change block when metadata.pageChanged is absent', () => {
+    const md = buildChatMarkdown({
+      title: 'T',
+      chatId: 'c',
+      rows: [row({ role: 'assistant', content: 'answer' })],
+    });
+    expect(md).not.toContain(
+      'The user edited this page before this turn; the diff the agent saw:',
+    );
+  });
+
+  // #288 F1/F2: an empty page title must render the BARE heading with no
+  // `("…")` suffix (the `pc.title ? … : …` false branch).
+  it('renders the page-change heading with no title suffix when title is empty', () => {
+    const md = buildChatMarkdown({
+      title: 'T',
+      chatId: 'c',
+      rows: [
+        row({
+          role: 'assistant',
+          content: 'answer',
+          metadata: {
+            pageChanged: { title: '', diff: '@@ -1 +1 @@\n-old\n+new' },
+          } as never,
+        }),
+      ],
+    });
+    // Bare heading, single line, no parenthesized title.
+    expect(md).toContain(
+      '> **📝 The user edited this page before this turn; the diff the agent saw:**',
+    );
+    expect(md).not.toContain('("');
+    expect(md).toContain('-old');
+  });
+
+  // #288 F1: the page title is UNTRUSTED cross-user data, so a title carrying a
+  // newline / backtick / `"` / `<`/`>` must be neutralized by escapeAttr before
+  // it is interpolated into the `> **…**` blockquote heading — otherwise it
+  // could break the blockquote onto multiple lines or inject markup/HTML into
+  // the downloaded .md. escapeAttr strips `<>"` and collapses whitespace runs to
+  // a single space, so `Ev"il\n> `x` <b>` becomes ``Evil `x` b``.
+  it('escapes an untrusted page title in the page-change heading', () => {
+    const md = buildChatMarkdown({
+      title: 'T',
+      chatId: 'c',
+      rows: [
+        row({
+          role: 'assistant',
+          content: 'answer',
+          metadata: {
+            pageChanged: {
+              title: 'Ev"il\n> `x` <b>',
+              diff: '@@ -1 +1 @@\n-old\n+new',
+            },
+          } as never,
+        }),
+      ],
+    });
+    // The heading stays a single blockquote line with the escaped title.
+    expect(md).toContain(
+      '> **📝 The user edited this page before this turn; the diff the agent saw: ("Evil `x` b")**',
+    );
+    // No raw attribute/markup breakers survived from the title.
+    expect(md).not.toContain('Ev"il');
+    expect(md).not.toContain('<b>');
+  });
+
+  // #288 review F1: escapeAttr ALONE is insufficient for this MARKDOWN sink —
+  // link/image syntax survives it. A cross-user title with `![x](url)` /
+  // `[phish](url)` must NOT become a working remote image or clickable link in
+  // the downloaded .md; markdownHeadingSafe backslash-escapes `[`/`]` so both are
+  // inert. (Non-vacuous: fails against the escapeAttr-only version, which left
+  // `](https://` intact.)
+  it('neutralizes markdown link/image syntax in an untrusted page title', () => {
+    const md = buildChatMarkdown({
+      title: 'T',
+      chatId: 'c',
+      rows: [
+        row({
+          role: 'assistant',
+          content: 'answer',
+          metadata: {
+            pageChanged: {
+              title:
+                '![x](https://attacker.example/t.png) and [click](https://phish.example)',
+              diff: '@@ -1 +1 @@\n-old\n+new',
+            },
+          } as never,
+        }),
+      ],
+    });
+    // No WORKING image/link syntax survives — the `[…]` sits escaped as `\[…\]`,
+    // so the unescaped `![x](` image and `[click](` link markers are gone. (We
+    // deliberately do NOT assert `not.toContain('](https://')`: after escaping the
+    // literal `\](https://` still contains `](https://` as a raw substring — that
+    // check would false-fail even though the link is inert.)
+    expect(md).not.toContain('![x](');
+    expect(md).not.toContain('[click](');
+    // The brackets are backslash-escaped, so `[text](url)`/`![text](url)` are inert.
+    expect(md).toContain('\\[');
+    expect(md).toContain('\\]');
+    // The heading stays a SINGLE blockquote line (no newline injected).
+    const headingLine = md
+      .split('\n')
+      .find((l) => l.includes('the diff the agent saw:'));
+    expect(headingLine).toBeDefined();
+    expect(headingLine).toContain('\\[x\\]');
+    expect(headingLine).toContain('\\[click\\]');
+  });
+
+  // #288 internal review Finding 2: a NON-empty title made up entirely of
+  // escapeAttr breakers (`<>"`) escapes to '' — the ternary must then fall to the
+  // BARE heading with NO `("…")` suffix. Locks the ternary-on-escaped-value
+  // behavior (distinct from the empty-string input test above).
+  it('renders the bare heading for a title that escapes to empty', () => {
+    const md = buildChatMarkdown({
+      title: 'T',
+      chatId: 'c',
+      rows: [
+        row({
+          role: 'assistant',
+          content: 'answer',
+          metadata: {
+            pageChanged: { title: '<>"', diff: '@@ -1 +1 @@\n-old\n+new' },
+          } as never,
+        }),
+      ],
+    });
+    expect(md).toContain(
+      '> **📝 The user edited this page before this turn; the diff the agent saw:**',
+    );
+    expect(md).not.toContain('("');
+    expect(md).toContain('-old');
+  });
+
   it('escapes embedded triple-backtick fences with a longer delimiter', () => {
     const md = buildChatMarkdown({
       title: 'T',

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

@@ -15,6 +15,7 @@
  */
 
 import type { AiChatMessage } from '@docmost/db/types/entity.types';
+import { escapeAttr } from './ai-chat.prompt';
 
 /** Supported export label languages. Defaults to English. */
 export type ExportLang = 'en' | 'ru';
@@ -63,6 +64,7 @@ const LABELS: Record<
     tools: Record<string, string>;
     ranTool: (name: string) => string;
     stillGenerating: string;
+    pageEditedByUser: string;
   }
 > = {
   en: {
@@ -83,6 +85,8 @@ const LABELS: Record<
     ranTool: (name) => `Ran tool ${name}`,
     stillGenerating:
       'This message is still being generated — the export captured a partial, in-progress response.',
+    pageEditedByUser:
+      'The user edited this page before this turn; the diff the agent saw:',
   },
   ru: {
     untitled: 'Без названия',
@@ -102,9 +106,29 @@ const LABELS: Record<
     ranTool: (name) => `Выполнил инструмент ${name}`,
     stillGenerating:
       'Это сообщение всё ещё генерируется — экспорт захватил частичный, незавершённый ответ.',
+    pageEditedByUser:
+      'Пользователь изменил страницу перед этим ходом; дифф, который видел агент:',
   },
 };
 
+/**
+ * Make an untrusted title safe to interpolate into a Markdown blockquote
+ * HEADING. escapeAttr() neutralizes the XML/HTML breakers (`<` `>` `"`) and
+ * collapses whitespace for the PROMPT sink (`page="…"`), but this export sink is
+ * MARKDOWN — link/image syntax survives escapeAttr. So additionally backslash-
+ * escape `[` and `]`: that disables both `[text](url)` links and `![text](url)`
+ * images, so a cross-user title like `![x](http://evil)` or `[phish](http://evil)`
+ * cannot inject a remote (auto-loading) image or a clickable link into the
+ * downloaded .md disguised as a trusted system annotation. A bare `(url)` with no
+ * preceding `[]` is inert Markdown, so brackets are the only security-critical
+ * characters here. (We leave backticks to escapeAttr's whitespace pass — a title
+ * shown as inline code cannot escape the blockquote line or load a resource, so
+ * it is not a security concern for this sink.)
+ */
+function markdownHeadingSafe(title: string): string {
+  return escapeAttr(title).replace(/[[\]]/g, (m) => `\\${m}`);
+}
+
 /** True for AI SDK tool parts (static `tool-*` or `dynamic-tool`). */
 function isToolPart(type: string): boolean {
   return type.startsWith('tool-') || type === 'dynamic-tool';
@@ -208,6 +232,23 @@ function rowParts(row: AiChatMessage): ExportPart[] {
     : [{ type: 'text', text: row.content ?? '' }];
 }
 
+/** The persisted page-change diff the agent saw this turn (#274), when any. */
+function pageChangedOf(
+  row: AiChatMessage,
+): { title: string; diff: string } | undefined {
+  const meta = (row.metadata ?? {}) as {
+    pageChanged?: { title?: string; diff?: string };
+  };
+  const pc = meta.pageChanged;
+  if (pc && typeof pc.diff === 'string' && pc.diff.trim().length > 0) {
+    return {
+      title: typeof pc.title === 'string' ? pc.title : '',
+      diff: pc.diff,
+    };
+  }
+  return undefined;
+}
+
 /**
  * Serialize a chat to a Markdown string from its persisted rows. Source = DB
  * ONLY (no live client state). A row whose `status` is still 'streaming' is an
@@ -266,6 +307,26 @@ export function buildChatMarkdown(args: {
       blocks.push(`<!-- ${iso} -->`);
     }
 
+    // Page-change observability (#274): show the diff the agent saw at the start
+    // of this turn, before its response, so the export reflects the stale-page
+    // warning the model received.
+    const pc = pageChangedOf(row);
+    if (pc) {
+      // The page title is UNTRUSTED cross-user data (a collaborative page's title
+      // controllable by another user). escapeAttr() alone (the prompt sink) is
+      // INSUFFICIENT here: this is a MARKDOWN sink, so we neutralize link/image
+      // syntax too (backslash-escaping `[`/`]`) before interpolating it into this
+      // `> **…**` blockquote heading — otherwise `![x](url)` / `[phish](url)` would
+      // inject a remote image or clickable link into the downloaded .md. An
+      // all-`<>"` title escapes to empty and correctly falls to the bare heading.
+      // The diff body is already safe via fence(). (#288 review F1.)
+      const safeTitle = markdownHeadingSafe(pc.title);
+      const heading = safeTitle
+        ? `${L.pageEditedByUser} ("${safeTitle}")`
+        : L.pageEditedByUser;
+      blocks.push(`> **📝 ${heading}**\n\n${fence(pc.diff, 'diff')}`);
+    }
+
     blocks.push(...renderMessageParts(rowParts(row), lang));
 
     // A still-'streaming' row is an interrupted/in-progress turn captured by the

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 ' +
@@ -432,6 +437,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 +450,10 @@ export class AiChatToolsService {
           "new top-level comment REQUIRES a `selection`. Replies inherit the " +
           "parent's anchor and take no selection. If the call fails with a " +
           '"selection not found" error, retry with a corrected EXACT selection ' +
-          'copied verbatim from a single paragraph/block. Reversible via the ' +
-          'comment UI.',
+          'copied verbatim from a single paragraph/block. You may also attach a ' +
+          '`suggestedText` proposing a replacement for the `selection` (a human ' +
+          'applies it from the UI); when set, the `selection` must occur exactly ' +
+          'once in the page. Reversible via the comment UI.',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page to comment on.'),
           content: z.string().describe('The comment body as Markdown.'),
@@ -464,24 +475,57 @@ export class AiChatToolsService {
               'Optional id of a TOP-LEVEL comment to reply to (one level ' +
                 'of replies only).',
             ),
+          suggestedText: z
+            .string()
+            .min(1)
+            .max(2000)
+            .optional()
+            .describe(
+              'Optional proposed replacement (PLAIN TEXT) for the `selection`, ' +
+                'applied by a human via the UI (never auto-applied). REQUIRES a ' +
+                '`selection`; NOT allowed on a reply. When set, the `selection` ' +
+                'must be UNIQUE in the page — expand it with surrounding context ' +
+                '(still <=250 chars) if it occurs more than once, or the call is ' +
+                'refused.',
+            ),
         }),
-        execute: async ({ pageId, content, selection, parentCommentId }) => {
-          // createComment(pageId, content, type, selection?, parentCommentId?).
-          // Top-level comments are inline and must carry a selection to anchor
-          // on; replies inherit the parent's anchor (no selection). Throwing
-          // here surfaces a tool error to the model (Vercel `ai` SDK) so the
-          // agent retries with a better selection — do not catch/suppress it.
+        execute: async ({
+          pageId,
+          content,
+          selection,
+          parentCommentId,
+          suggestedText,
+        }) => {
+          // createComment(pageId, content, type, selection?, parentCommentId?,
+          // suggestedText?). Top-level comments are inline and must carry a
+          // selection to anchor on; replies inherit the parent's anchor (no
+          // selection). Throwing here surfaces a tool error to the model (Vercel
+          // `ai` SDK) so the agent retries with a better selection — do not
+          // catch/suppress it.
           if (!parentCommentId && (!selection || !selection.trim())) {
             throw new Error(
               "createComment requires a 'selection' (exact text to anchor on) for a new top-level comment.",
             );
           }
+          if (suggestedText !== undefined) {
+            if (parentCommentId) {
+              throw new Error(
+                "createComment: 'suggestedText' cannot be attached to a reply; it applies only to a top-level inline comment.",
+              );
+            }
+            if (!selection || !selection.trim()) {
+              throw new Error(
+                "createComment: 'suggestedText' requires a 'selection' to anchor and rewrite.",
+              );
+            }
+          }
           const result = await client.createComment(
             pageId,
             content,
             'inline',
             selection,
             parentCommentId,
+            suggestedText,
           );
           const data = (result?.data ?? {}) as { id?: string };
           return { commentId: data.id, pageId };
@@ -519,6 +563,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. ' +
@@ -692,85 +740,25 @@ export class AiChatToolsService {
         async ({ pageId }) => await client.stashPage(pageId),
       ),
 
-      patchNode: tool({
-        description:
-          'Replace a single content block (by id) with a new ProseMirror ' +
-          'node; the replacement keeps the same nodeId. Example node: a ' +
-          'paragraph {"type":"paragraph","content":[{"type":"text","text":"Hello"}]} ' +
-          'or a heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible: ' +
-          'the previous version is kept in page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          nodeId: z
-            .string()
-            .describe('The block id to replace (from getOutline/getPageJson).'),
-          node: z
-            .any()
-            .describe(
-              'The replacement ProseMirror node, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-        }),
-        execute: async ({ pageId, nodeId, node }) => {
-          // Parity with the standalone MCP server (index.ts patch_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Schema + description from the shared registry (identical across both
+      // transports). The execute body keeps its OWN parseNodeArg normalization:
+      // the model sometimes serializes the node as a JSON string, and we parse it
+      // before the client's typeof-object guard rejects it (parity with the
+      // standalone MCP server, index.ts patch_node).
+      patchNode: sharedTool(
+        sharedToolSpecs.patchNode,
+        async ({ pageId, nodeId, node }) => {
           const parsedNode = parseNodeArg(node);
           return await client.patchNode(pageId, nodeId, parsedNode);
         },
-      }),
+      ),
 
-      insertNode: tool({
-        description:
-          'Insert a ProseMirror node relative to an anchor, or append it at ' +
-          'the top level. For before/after you MUST provide EXACTLY ONE of ' +
-          'anchorNodeId or anchorText. Example node: a paragraph ' +
-          '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-          'heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible ' +
-          'via page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          node: z
-            .any()
-            .describe(
-              'The ProseMirror node to insert, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-          position: z
-            .enum(['before', 'after', 'append'])
-            .describe('Where to insert relative to the anchor.'),
-          anchorNodeId: z
-            .string()
-            .optional()
-            .describe('Anchor block id (for before/after).'),
-          anchorText: z
-            .string()
-            .optional()
-            .describe(
-              'Anchor text fragment (for before/after), matched against the ' +
-                "block's literal rendered plain text (no markdown). " +
-                'Markdown/emoji are tolerated as a fallback; prefer plain text ' +
-                'or anchorNodeId.',
-            ),
-        }),
-        execute: async ({
-          pageId,
-          node,
-          position,
-          anchorNodeId,
-          anchorText,
-        }) => {
-          // Parity with the standalone MCP server (index.ts insert_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Shared registry schema + description; execute retains parseNodeArg on the
+      // incoming node (parity with the standalone MCP server, index.ts
+      // insert_node).
+      insertNode: sharedTool(
+        sharedToolSpecs.insertNode,
+        async ({ pageId, node, position, anchorNodeId, anchorText }) => {
           const parsedNode = parseNodeArg(node);
           return await client.insertNode(pageId, parsedNode, {
             position,
@@ -778,7 +766,7 @@ export class AiChatToolsService {
             anchorText,
           });
         },
-      }),
+      ),
 
       deleteNode: sharedTool(
         sharedToolSpecs.deleteNode,
@@ -821,6 +809,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 +833,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 +849,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 +880,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 +910,10 @@ export class AiChatToolsService {
         async ({ historyId }) => await client.restorePageVersion(historyId),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): deliberately omits the
+      // `deleteComments` schema field (comment-deletion guardrail) and carries a
+      // much shorter description; the standalone MCP `docmost_transform` exposes
+      // the full helper catalogue. Different schema, so kept per-layer.
       transformPage: tool({
         description:
           'Run a sandboxed JS transform of the form `(doc, ctx) => doc` over a ' +

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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