fix(#300 ui): flip avatar hierarchy on comments, make launcher visible

Two visual defects in the agent avatar stack (PR #304), missed by the
code-only review:

- The launcher (human) avatar was fully occluded behind the opaque agent
  glyph — the container was exactly the glyph size, so the launcher sat
  underneath it. Enlarge the container by an overhang and vertically center
  the glyph so the launcher peeks out at the bottom-right and stays visible.
- On comments the human creator stayed the PRIMARY avatar and name while the
  stack was crammed into the old badge slot, duplicating the identity and
  failing the "agent is primary" requirement. AgentAvatarStack gains a
  showName prop; with showName=false it now replaces the leading avatar for
  agent comments, and the name slot renders agent.name (+ dimmed
  · launcher.name). Non-agent comments are byte-identical to before;
  history-item keeps the default (names shown).

Tests: add showName=false and external-MCP (no-launcher) coverage, assert
no identity duplication. client tsc clean, 9 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -190,20 +190,6 @@ MCP_DOCMOST_PASSWORD=
 # Default 900000 (15 min).
 # AI_MCP_CALL_TIMEOUT_MS=900000
 
-# --- Autonomous / detached agent runs (settings.ai.autonomousRuns) ---
-# Opt-in per workspace (AI settings; off by default). When on, a chat turn becomes
-# a server-side RUN that survives a browser disconnect — only an explicit Stop ends
-# it, and a client reconnects/live-follows the run.
-#
-# DEPLOY CONSTRAINT — SINGLE-INSTANCE ONLY in phase 1: Stop and the in-process
-# AbortController that backs it are process-local, so a Stop only aborts a run
-# executing on the SAME replica that owns it (cross-instance pub/sub stop is phase
-# 2 and not yet reliable). Do NOT enable autonomousRuns on a horizontally-scaled
-# deployment (multiple replicas behind a load balancer, or Docmost cloud
-# CLOUD=true) — run a single instance instead. The server logs a startup WARNING
-# when it detects a multi-instance deployment (CLOUD=true) so the constraint is
-# visible, and a startup sweep settles any run left dangling by a restart.
-
 # --- Anonymous public-share AI assistant ---
 # Opt-in per workspace (AI settings -> "public share assistant"; off by default).
 # When enabled, anonymous visitors of a published share can ask an AI about that

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.
 
 ---
 
@@ -267,7 +278,6 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
    - `core/ai-chat/tools/` — the agent's ~40 read+write tools. Every tool runs under the **calling user's** CASL permissions via a per-user loopback access token (`docmost-client.loader.ts`), so the agent can never exceed what the user could do. Only **reversible** operations are exposed (page history + trash; no permanent delete). Agent edits get an "AI agent" provenance badge in page history (`20260616T130000-agent-provenance` migration).
    - `core/ai-chat/embedding/` — RAG indexer + a BullMQ consumer on `AI_QUEUE` that embeds pages into `page_embeddings` (vector search), complementing Postgres full-text search. Pages are (re)indexed on edit; `AI_EMBEDDING_TIMEOUT_MS` bounds a hung embeddings endpoint.
    - `core/ai-chat/external-mcp/` — admins can attach external MCP servers (e.g. Tavily) to give the agent web access. **`ssrf-guard.ts` validates outbound MCP URLs against SSRF** — keep that guard in the path when touching external-MCP connection logic.
-   - `core/ai-chat/ai-chat-run.service.ts` + `ai_chat_runs` — **detached/autonomous agent runs** (`#184`), behind the per-workspace `settings.ai.autonomousRuns` flag (off by default). When on, a turn becomes a server-side RUN that survives a browser disconnect; only an explicit `POST /ai-chat/stop` ends it, and a client reconnects/live-follows via `POST /ai-chat/run`. **DEPLOY CONSTRAINT — single-instance only in phase 1:** Stop and the AbortController that backs it are process-local, so a Stop only aborts a run executing on the **same** replica that owns it (cross-instance pub/sub stop is phase 2). Do **not** enable `autonomousRuns` on a horizontally-scaled deployment (multiple replicas behind a load balancer, or Docmost cloud `CLOUD=true`) — run a single instance instead. The server logs a startup WARNING when it detects a multi-instance deployment (`CLOUD=true`) so the constraint is visible. The startup sweep settles any run left dangling by a restart.
 
 ### Client structure
 Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:

CHANGELOG.md

@@ -14,8 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Place several images side by side in a row.** A new "Inline (side by
   side)" alignment mode in the image bubble menu renders consecutive inline
-  images as a row that wraps onto the next line on narrow screens. Unlike the
-  float modes, text does not wrap around inline images. The mode round-trips
+  images as a row that wraps onto the next line on narrow screens. The row is
+  centered horizontally by default in modern browsers (CSS `:has()`), falling
+  back to start-aligned rows in browsers without support. Unlike the float
+  modes, text does not wrap around inline images. The mode round-trips
   losslessly through markdown as `data-align`, like the other alignment
   values.
 
@@ -70,19 +72,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   append/prepend fragments, nor to COMMENT bodies — a comment may legitimately
   contain a standalone footnote definition, which canonicalization would drop.
   (#228)
-- **Detached, autonomous agent runs that survive a browser disconnect.** When the
-  new `settings.ai.autonomousRuns` workspace flag is on (off by default), an
-  AI-chat turn becomes a first-class, server-side RUN tracked in a new
-  `ai_chat_runs` table instead of a socket-bound stream: closing the tab or
-  losing the connection no longer aborts the turn — it keeps executing and
-  persisting server-side, and only an explicit Stop ends it. A client can
-  reconnect and live-follow (or stop) an in-flight run via `POST /ai-chat/run`
-  (resolve the latest run + its assistant message for a chat) and
-  `POST /ai-chat/stop` (stop by `runId` or `chatId`). A partial unique index
-  enforces one active run per chat, and a startup sweep settles any run left
-  dangling by a restart. Phase 1 is single-instance-only (cross-instance Stop is
-  not yet reliable); the server warns at startup on a horizontally-scaled
-  deployment. (#184)
 - **Out-of-band page transfer via an in-RAM blob sandbox (`stash_page`).** A
   new MCP tool serializes a whole page (its full ProseMirror JSON, with every
   internal image/file mirrored) into an ephemeral in-RAM blob and returns only
@@ -97,6 +86,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   with the `||text||` input rule; the rendered span blurs until clicked to reveal.
   The mark is preserved losslessly through Markdown export/import (as a raw
   `<span data-spoiler="true">…</span>`) and on public shares. (#259)
+- **Dock the AI chat window into the side menu.** The floating chat window can
+  be pinned to the sidebar — drag it onto the navbar (a drop-zone highlight
+  shows where it lands) or use the new "Dock to sidebar" header button; while
+  docked it fills the sidebar area and follows its live size. "Undock" (or
+  dragging it back out) restores the floating window, a collapsed/absent
+  sidebar falls back to floating, and the docked state survives a reload.
+  (#276, #282)
+- **Hovering commented text shows the comment thread in a tooltip.** Pointing
+  at a highlighted comment mark pops a small card with the author and plain
+  text of the root comment and its replies, so a thread can be skimmed without
+  opening the side panel. The card appears after a short delay (no flicker on a
+  passing glance), skips resolved and text-less threads, and dismisses on
+  scroll or click — clicking a mark still opens the comments panel. (#268,
+  #271)
+- **"Move to trash" button in the temporary-note banner.** Besides "Make
+  permanent", the banner on an open temporary note now also offers to trash the
+  note immediately instead of waiting out its lifetime. It reuses the regular
+  soft-delete path, so the "Page moved to trash" undo toast is the safety net —
+  no confirmation dialog. (#273, #277)
+- **Code-block controls float as an overlay instead of taking a row above the
+  code.** The language selector and copy button now sit in the block's top-right
+  corner, and the selector stays invisible until the block is hovered or the
+  selector is focused, so reading code is chrome-free. In read-only views only
+  the copy button renders. (#275, #278)
+- **The AI agent is told about your page edits between turns.** The server
+  snapshots the open page's Markdown at the end of every agent turn and, on the
+  next turn, injects a unified diff of what changed in between, so the agent
+  knows its earlier copy of the page is stale and builds on the user's edits
+  instead of reverting or overwriting them. The diff is whitespace-normalized
+  (pure formatting churn injects nothing) and size-capped, with a hint to
+  re-read the full page via `getPage` when truncated. (#274, #281)
+- **Stress-accent button (U+0301) in the bubble menu.** Select a vowel and
+  toggle a combining acute accent over it — a Russian-style stress mark. The
+  accent is stored as plain text (no custom mark), so it survives Markdown/HTML
+  export, full-text search and public shares unchanged; the toggle is a single
+  undo step and re-clicking removes the accent. (#270, #280)
+- **Reading position survives a reload.** The editor remembers how far you
+  scrolled in each page (per tab, in `sessionStorage`) and restores that
+  position after an F5 or reopening the document, waiting for the collaborative
+  content to finish laying out first. A URL `#hash` anchor still wins — restore
+  is a no-op then. (#266, #267)
+- **The slash menu finds commands typed in the wrong keyboard layout.** A query
+  typed with the wrong layout active (e.g. `/сщву` for `/code`, or `/cyjcrf`
+  for the Cyrillic «сноска» → Footnote) is additionally remapped ЙЦУКЕН↔QWERTY
+  by physical key position and matched against the commands; genuine Cyrillic
+  search terms keep priority over remapped candidates, and short wrong-layout
+  prefixes match by command title. (#283, #285, #287)
 
 ### Changed
 
@@ -162,6 +198,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   emits a single-use "intentional clear" signal that lets exactly that one empty
   write through the guard, so genuinely emptying a page is persisted while
   accidental empties are blocked. (#248, #251)
+- **Ctrl+Z works again right after using a table menu.** Closing a table
+  row/column menu (grip or chevron) left focus on the menu's portaled target
+  outside the editor, so undo keystrokes went nowhere until you clicked back
+  into a cell. The editor is now refocused after the menu closes — unless you
+  deliberately moved focus to another input or editable (e.g. the page title).
+  (#269, #279)
+- **The AI reindex progress counter no longer freezes at 0.** Right after
+  "Reindex now" the client could read the stale pre-reindex snapshot of an
+  already-indexed workspace (`reindexing=false`, all pages counted) as
+  "finished" and stop polling on the very first tick, leaving the counter
+  frozen until a manual reload. Polling now keeps going until it has actually
+  observed the active run. (#262, #264)
+- **An MCP edit can no longer be silently lost to a duplicate collab document.**
+  When the agent addressed a page by its short slugId, the MCP opened a
+  collaboration document named after that slugId while the web editor always
+  uses the page's canonical UUID — two independent live documents for one page,
+  whose debounced stores clobbered each other. The MCP now resolves every page
+  id to the canonical UUID before opening the collab doc (a UUID input
+  short-circuits locally; a slugId is resolved once and cached). (#260, #265)
 
 ### Security
 

README.md

@@ -104,7 +104,7 @@ community feature, with no enterprise license. Open it from the page header; the
 - ✅ **Page templates** — flag a page as a template and embed its whole content live into other pages; edits to the template propagate to every place it is inserted (whole-page transclusion on top of the existing synced blocks).
 - ✅ **Public-share AI assistant** — anonymous visitors of a shared page can ask the AI agent, scoped strictly to that share's page tree (read-only, share-scoped search), behind a workspace toggle.
 - ✅ **Footnotes** — academic-style footnotes: a numbered superscript reference inline (read it in place via a hover popover), with the note text living as a real, editable block at the bottom of the page; auto-numbered, collaboration-safe, and round-trips through Markdown export/import and the AI agent / MCP.
-- ✅ **Temporary notes** — mark a note as temporary and it auto-moves to Trash after a configurable per-workspace lifetime (default 24h) unless made permanent first; create one in a click from the Home screen, any space overview, or the space sidebar, with a "Make permanent" rescue banner on the open note.
+- ✅ **Temporary notes** — create a note as temporary and it auto-moves to Trash after a configurable per-workspace lifetime (default 24h) unless made permanent first; create one in a click from the Home screen, any space overview.
 
 ### In progress
 
@@ -187,14 +187,17 @@ start the new migrations apply on top of your existing schema (`CREATE EXTENSION
 - Spaces
 - Permissions management
 - Groups
-- Comments (with resolve / re-open)
+- Comments (with resolve / re-open and hover tooltips showing the comment text)
 - Page history
 - Search
 - File attachments
 - Embeds (Airtable, Loom, Miro and more)
 - Translations (10+ languages)
 - Embedded MCP server (`/mcp`)
-- AI agent chat over your wiki (read + write, RAG search, external MCP / web access)
+- AI agent chat over your wiki (read + write, RAG search, external MCP / web access); the chat window docks into the side menu, and the agent is told about your in-page edits between turns
+- Code-block buttons as an overlay, with the language selector revealed on hover
+- Stress-accent button (U+0301) in the bubble menu
+- Reading scroll position restored on reload
 
 ### Screenshots
 

README.ru.md

@@ -105,7 +105,7 @@ real-time-коллаборации Docmost, поэтому запись нико
 - ✅ **Шаблоны страниц** — пометить страницу шаблоном и вставлять её содержимое живой ссылкой в другие страницы; правки шаблона распространяются на все места вставки (whole-page-транслюзия поверх существующих synced-блоков).
 - ✅ **AI-ассистент на публичных шарах** — анонимный зритель расшаренной страницы может спросить AI-агента, который ищет строго по дереву этой шары (read-only, share-scoped поиск), за тумблером воркспейса.
 - ✅ **Сноски** — сноски академического вида: нумерованная ссылка-надстрочник прямо в тексте (читается на месте во всплывающем окне по наведению), а текст сноски живёт реальным редактируемым блоком внизу страницы; авто-нумерация, безопасна для совместного редактирования, переживает экспорт/импорт Markdown и доступна AI-агенту / MCP.
-- ✅ **Временные заметки** — пометьте заметку временной, и она автоматически уедет в корзину по истечении настраиваемого срока жизни воркспейса (по умолчанию 24 ч), если её предварительно не сделать постоянной; создать такую можно в один клик с домашнего экрана, с обзора любого пространства или из сайдбара пространства, а на открытой заметке есть баннер «Сделать постоянной».
+- ✅ **Временные заметки** — создайте временную заметку, и она автоматически уедет в корзину по истечении настраиваемого срока жизни (по умолчанию 24 ч); создать такую можно в один клик с домашнего экрана, с обзора любого пространства или из сайдбара пространства.
 
 ### В процессе
 
@@ -174,14 +174,18 @@ dump/restore, существующий каталог данных переис
 - Пространства (Spaces)
 - Управление правами доступа
 - Группы
-- Комментарии (с резолвом / переоткрытием)
+- Комментарии (с резолвом / переоткрытием и всплывающими подсказками с текстом комментария при наведении)
 - История страниц
 - Поиск
 - Вложения файлов
 - Встраивания (Airtable, Loom, Miro и другие)
 - Переводы (10+ языков)
 - Встроенный MCP-сервер (`/mcp`)
-- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет)
+- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет); окно чата закрепляется в боковом меню, а агент узнаёт о ваших правках страницы между ходами
+- Кнопки код-блока оверлеем, селектор языка появляется при наведении
+- Кнопка «Ударение» (U+0301) в bubble-меню
+- Позиция чтения (прокрутка) восстанавливается после перезагрузки
+- Slash-меню терпимо к неправильной раскладке (ЙЦУКЕН↔QWERTY)
 
 ### Скриншоты
 

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.",

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

@@ -724,7 +724,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": "Ошибка",

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,119 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { Provider, createStore } from "jotai";
+import { AgentAvatarStack } from "./agent-avatar-stack";
+import {
+  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>;
+
+function renderStack(props: Props) {
+  const store = createStore();
+  store.set(aiChatDraftAtom, "leftover draft from another chat");
+  const utils = render(
+    <Provider store={store}>
+      <MantineProvider>
+        <AgentAvatarStack {...props} />
+      </MantineProvider>
+    </Provider>,
+  );
+  return { store, ...utils };
+}
+
+describe("AgentAvatarStack", () => {
+  it("internal chat WITH role: emoji glyph in front + human launcher behind", () => {
+    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("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 in front, NO launcher behind", () => {
+    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,209 @@
+import { Avatar, 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;
+}
+
+// Same violet token as the former AiAgentBadge (which used color="violet").
+const AGENT_COLOR = "violet";
+const GLYPH_SIZE = 38;
+const LAUNCHER_SIZE = 22;
+// How far the launcher avatar sticks out past the agent's bottom-right corner, so
+// the "human behind" reads as behind (lower z-index) yet stays clearly visible.
+const LAUNCHER_OVERHANG = 8;
+
+/**
+ * The front avatar. Image-source priority (#300):
+ *   1. agent.avatarUrl -> a real avatar image (external MCP agent account).
+ *   2. agent.emoji     -> the role emoji on a violet circle.
+ *   3. otherwise       -> the IconSparkles glyph on a violet circle (fallback).
+ */
+function AgentGlyph({ agent }: { agent: AgentInfo }) {
+  if (agent.avatarUrl) {
+    return (
+      <CustomAvatar
+        size={GLYPH_SIZE}
+        avatarUrl={agent.avatarUrl}
+        name={agent.name}
+      />
+    );
+  }
+
+  if (agent.emoji) {
+    return (
+      <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
+        <span style={{ fontSize: Math.round(GLYPH_SIZE * 0.5) }} aria-hidden>
+          {agent.emoji}
+        </span>
+      </Avatar>
+    );
+  }
+
+  return (
+    <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
+      <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
+    </Avatar>
+  );
+}
+
+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 in front, and — for an
+ * internal AI chat — the HUMAN who launched it as a smaller avatar offset behind.
+ * 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 && (
+        <Box pos="absolute" bottom={0} right={0} style={{ zIndex: 0 }}>
+          <CustomAvatar
+            size={LAUNCHER_SIZE}
+            avatarUrl={launcher.avatarUrl}
+            name={launcher.name}
+            style={{ border: "2px solid var(--mantine-color-body)" }}
+          />
+        </Box>
+      )}
+      {/* Pin the agent glyph to the top-left at its own size; the launcher then
+          overhangs it by LAUNCHER_OVERHANG at the bottom-right and stays visible. */}
+      <Box
+        style={{
+          position: "relative",
+          zIndex: 1,
+          width: GLYPH_SIZE,
+          height: GLYPH_SIZE,
+        }}
+      >
+        <AgentGlyph agent={agent} />
+      </Box>
+    </Box>
+  );
+
+  return (
+    <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
+      <Tooltip label={tooltip} withArrow>
+        {stack}
+      </Tooltip>
+      {showName && (
+        <Group gap={4} wrap="nowrap" style={{ minWidth: 0 }}>
+          <Text size="xs" fw={600} lineClamp={1} lh={1.2}>
+            {agent.name}
+          </Text>
+          {launcher && (
+            <>
+              <Text size="xs" c="dimmed" fw={400} aria-hidden>
+                ·
+              </Text>
+              <Text size="xs" c="dimmed" fw={400} lineClamp={1} lh={1.2}>
+                {launcher.name}
+              </Text>
+            </>
+          )}
+        </Group>
+      )}
+    </Group>
+  );
+}
+
+export default AgentAvatarStack;

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

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

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

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

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

@@ -19,7 +19,7 @@ import {
   IconPlus,
   IconX,
 } from "@tabler/icons-react";
-import { useAtom, useAtomValue, useSetAtom } from "jotai";
+import { useAtom, useSetAtom } from "jotai";
 import { useLocation, useMatch } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { useQueryClient } from "@tanstack/react-query";
@@ -41,24 +41,13 @@ import { extractPageSlugId } from "@/lib";
 import {
   AI_CHATS_RQ_KEY,
   AI_CHAT_MESSAGES_RQ_KEY,
-  AI_CHAT_RUN_RQ_KEY,
   useAiChatMessagesQuery,
-  useAiChatRunQuery,
   useAiChatsQuery,
   useAiRolesQuery,
 } from "@/features/ai-chat/queries/ai-chat-query.ts";
-import {
-  shouldClearLatchOnQueryError,
-  shouldClearStoppingLatch,
-  shouldObserveRun,
-} from "@/features/ai-chat/utils/run-polling.ts";
-import { workspaceAtom } from "@/features/user/atoms/current-user-atom";
 import ConversationList from "@/features/ai-chat/components/conversation-list.tsx";
 import ChatThread from "@/features/ai-chat/components/chat-thread.tsx";
-import {
-  exportAiChat,
-  stopRun,
-} from "@/features/ai-chat/services/ai-chat-service.ts";
+import { exportAiChat } from "@/features/ai-chat/services/ai-chat-service.ts";
 import { useChatSession } from "@/features/ai-chat/hooks/use-chat-session.ts";
 import {
   shouldCollapseOnOutsidePointer,
@@ -245,147 +234,6 @@ export default function AiChatWindow() {
   const { data: messageRows, isLoading: messagesLoading } =
     useAiChatMessagesQuery(activeChatId ?? undefined);
 
-  // #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
-  // this workspace. The reconnect endpoint itself is NOT flag-gated server-side
-  // (it is only owner-gated and returns `{ run: null }` when the chat has no
-  // run); but when the feature is off no runs are ever created, so polling it
-  // would always come back empty — we gate it off here to avoid pointless polls.
-  const workspace = useAtomValue(workspaceAtom);
-  const autonomousRunsEnabled =
-    workspace?.settings?.ai?.autonomousRuns === true;
-
-  // Whether THIS tab is the one actively streaming the open chat's run locally
-  // (it started the run here and holds the SSE). Reported up from ChatThread. We
-  // are the STREAMER while true and a passive OBSERVER while false — the basis of
-  // the observer-vs-streamer detection. Reset to false by the fresh ChatThread's
-  // mount effect on every chat switch.
-  const [localStreaming, setLocalStreaming] = useState(false);
-  const onStreamingChange = useCallback((streaming: boolean) => {
-    setLocalStreaming(streaming);
-  }, []);
-
-  // #184 Stop wiring. While a detached run is being stopped we SUPPRESS the
-  // observer merge so the stopping run's still-persisting output does not
-  // re-stream back into view between the moment the user pressed Stop and the run
-  // actually settling as 'aborted' server-side. Polling itself keeps running (so
-  // the terminal transition is still detected) — only the visual merge is gated.
-  // Cleared when the run is observed terminal (below) or the chat is switched.
-  const [stoppingRun, setStoppingRun] = useState(false);
-  // Reset the stopping latch whenever the open chat changes: it is scoped to the
-  // run of the previously-open chat.
-  useEffect(() => {
-    setStoppingRun(false);
-  }, [activeChatId]);
-
-  // Authoritative stop of the open chat's detached run (the Stop button in
-  // autonomous mode). Latch "stopping" first (suppresses the re-stream flash),
-  // then request the server stop — the ONLY thing that ends a detached run; a mere
-  // local SSE abort is a client disconnect the server ignores. On failure we
-  // release the latch so the observer resumes (better to show the live run than to
-  // freeze the view) and surface the error.
-  const handleServerStop = useCallback(
-    (chatId: string): void => {
-      setStoppingRun(true);
-      // #234 F4: drop the PREVIOUS turn's run from the cache so `run` becomes null
-      // until the CURRENT turn's run is fetched fresh. Without this, once the local
-      // stream aborts (localStreaming -> false) the run query re-enables and
-      // react-query SYNCHRONOUSLY returns the still-cached prior terminal run; the
-      // terminal effect would then clear the stopping latch against that STALE run
-      // before the current turn's (still-running, detached, growing) run is ever
-      // observed — re-opening the observer merge and flashing the growing output
-      // over the frozen row. With the cache cleared the terminal effect's
-      // `if (!run) return` holds the latch until the current run itself is observed
-      // terminal (see shouldClearStoppingLatch).
-      queryClient.removeQueries({ queryKey: AI_CHAT_RUN_RQ_KEY(chatId) });
-      void stopRun(chatId).catch(() => {
-        setStoppingRun(false);
-        notifications.show({
-          message: t("Failed to stop the run"),
-          color: "red",
-        });
-      });
-    },
-    [t, queryClient],
-  );
-
-  // Poll the latest run of the open chat ONLY when we are a passive observer:
-  // feature on, a chat is open, and we are NOT the local streamer (the streamer
-  // already has the live SSE — polling/merging too would double-render). The
-  // query's own status-keyed refetchInterval stops once the run is terminal.
-  const { data: runData, isError: runQueryFailed } = useAiChatRunQuery(
-    activeChatId ?? undefined,
-    autonomousRunsEnabled && !localStreaming,
-  );
-  const run = runData?.run ?? null;
-
-  // Safety net (#234 F4 review): after handleServerStop clears the run cache,
-  // `run` is null until the current turn's run is fetched fresh, and the terminal
-  // effect below holds the latch via `if (!run) return`. If that refetch instead
-  // ERRORS PERMANENTLY (the GET-run keeps failing) while we are no longer the
-  // streamer, the run stays null, its status-keyed refetchInterval is off, and
-  // nothing would ever observe a terminal run — freezing the view with the
-  // observer merge suppressed. Release the latch on that error so the live view
-  // resumes rather than stays stuck (the local stopRun may already have succeeded
-  // independently).
-  //
-  // #234 F7: this must NOT fire on a TRANSIENT error while `run` is still an
-  // ACTIVE held run. In TanStack Query v5 (retry:false) the query's `data` is
-  // RETAINED on error, so `runQueryFailed` can be true while `run` is still
-  // pending/running — releasing then would re-open the observer merge and flash
-  // the growing detached run over the frozen row (the very flash F4 prevents). The
-  // decision is the pure, unit-tested `shouldClearLatchOnQueryError`, which gates
-  // on the run NOT being active: it cures only the genuine permanent-null-freeze
-  // (`run === null`) and never releases against an active run.
-  useEffect(() => {
-    if (
-      shouldClearLatchOnQueryError({
-        stoppingRun,
-        isLocalStreaming: localStreaming,
-        runQueryFailed,
-        run,
-      })
-    )
-      setStoppingRun(false);
-  }, [stoppingRun, localStreaming, runQueryFailed, run]);
-  // The run's incrementally-persisted assistant message to merge into the thread,
-  // but only while we are an observer (never when we are the streamer — guards
-  // against a stale poll fighting the live stream). Includes a terminal run so the
-  // final persisted output is shown on reopen.
-  const observedRow =
-    shouldObserveRun(run, localStreaming) && !stoppingRun
-      ? (runData?.message ?? null)
-      : null;
-
-  // When the observed run reaches a terminal status, do a final messages refetch
-  // so the persisted final state (token/context badge, export source) is shown,
-  // then the query's refetchInterval has already stopped polling. Deduped per run
-  // id so it fires exactly once per run, not on every subsequent poll-less render.
-  const finalizedRunIdRef = useRef<string | null>(null);
-  useEffect(() => {
-    if (!run || !activeChatId) return;
-    if (run.status === "pending" || run.status === "running") {
-      // Active again (a new run) — re-arm so its terminal transition fires once.
-      finalizedRunIdRef.current = null;
-      return;
-    }
-    // Terminal: a stop we requested has landed (or the run finished on its own),
-    // so release the stopping latch — the observer merge can now show the final
-    // persisted (aborted/finished) output without any live re-stream. The decision
-    // is the pure, unit-tested `shouldClearStoppingLatch` (run-polling.ts): release
-    // ONLY when we requested a stop, this tab is no longer the streamer, AND the
-    // CURRENT run is terminal. The #234 F4 cache removal in handleServerStop makes
-    // `run` null (this branch's `if (!run) return` above holds) until the current
-    // turn's run is fetched fresh, so the latch can never clear against a stale
-    // cached run.
-    if (shouldClearStoppingLatch({ stoppingRun, run, isLocalStreaming: localStreaming }))
-      setStoppingRun(false);
-    if (finalizedRunIdRef.current === run.id) return;
-    finalizedRunIdRef.current = run.id;
-    queryClient.invalidateQueries({
-      queryKey: AI_CHAT_MESSAGES_RQ_KEY(activeChatId),
-    });
-  }, [run, activeChatId, queryClient, stoppingRun, localStreaming]);
-
   // The page the user is currently viewing. AiChatWindow lives in a pathless
   // parent layout route, so useParams() can't see :pageSlug. Match the full
   // pathname against the authenticated page route instead so "the current page"
@@ -1034,18 +882,6 @@ export default function AiChatWindow() {
               assistantName={currentRole?.name}
               onTurnFinished={onTurnFinished}
               onServerChatId={onServerChatId}
-              // #184: live-follow a still-running run when we reopened the chat as
-              // a passive observer; null when there is nothing to observe or this
-              // tab is the streamer. onStreamingChange lets the window stop polling
-              // while we are the streamer.
-              observedRow={observedRow}
-              onStreamingChange={onStreamingChange}
-              // #184: in autonomous mode the Stop button must hit the authoritative
-              // server stop (a local SSE abort is a client disconnect the server
-              // ignores). onServerStop also arms the "stopping" latch above so the
-              // stopped run's output does not re-stream via the observer merge.
-              autonomousRunsEnabled={autonomousRunsEnabled}
-              onServerStop={handleServerStop}
             />
           )}
         </div>

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

@@ -11,7 +11,6 @@ const h = vi.hoisted(() => ({
     onFinish: null as null | ((arg: Record<string, unknown>) => void),
     sendMessage: vi.fn(),
     stop: vi.fn(),
-    setMessages: vi.fn(),
     transport: null as null | {
       prepareSendMessagesRequest: (arg: {
         messages: unknown[];
@@ -31,8 +30,6 @@ vi.mock("@ai-sdk/react", () => ({
       status: h.state.status,
       stop: h.state.stop,
       error: null,
-      // #184: ChatThread reads setMessages to merge a polled observer run.
-      setMessages: h.state.setMessages,
     };
   },
 }));
@@ -143,56 +140,3 @@ describe("ChatThread — send now (#198)", () => {
     expect(prep({ messages: [], body: {} }).body.interrupted).toBe(false);
   });
 });
-
-// #184 passive-observer merge: when reconnecting to a still-running run, the
-// parent feeds the polled run message via `observedRow`; ChatThread merges it via
-// setMessages — but ONLY when this tab is NOT itself streaming (the streamer's
-// SSE owns the view, so a stale observedRow must never overwrite it).
-describe("ChatThread — observer run merge (#184)", () => {
-  beforeEach(() => {
-    h.state.onFinish = null;
-    h.state.setMessages.mockReset();
-  });
-
-  const observedRow = {
-    id: "a-run",
-    role: "assistant",
-    content: "step 1\nstep 2",
-    metadata: {
-      parts: [{ type: "text", text: "step 1\nstep 2" }],
-    },
-    createdAt: "2026-01-01T00:00:00Z",
-  } as const;
-
-  function renderObserver(status: string) {
-    h.state.status = status;
-    render(
-      <MantineProvider>
-        <ChatThread
-          chatId="c1"
-          initialRows={[]}
-          onTurnFinished={vi.fn()}
-          observedRow={observedRow as never}
-        />
-      </MantineProvider>,
-    );
-  }
-
-  it("merges the polled run message when this tab is a passive observer", () => {
-    renderObserver("ready");
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
-    // The updater replaces/append the observed assistant row by id.
-    const updater = h.state.setMessages.mock.calls[0][0] as (
-      prev: { id: string; parts: { text: string }[] }[],
-    ) => { id: string; parts: { text: string }[] }[];
-    const merged = updater([{ id: "u1", parts: [{ text: "hi" }] }]);
-    expect(merged).toHaveLength(2);
-    expect(merged[1].id).toBe("a-run");
-    expect(merged[1].parts[0].text).toBe("step 1\nstep 2");
-  });
-
-  it("does NOT merge while THIS tab is the streamer (no double-render)", () => {
-    renderObserver("streaming");
-    expect(h.state.setMessages).not.toHaveBeenCalled();
-  });
-});

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

@@ -24,7 +24,6 @@ import {
 } from "@/features/ai-chat/utils/role-launch.ts";
 import { describeChatError } from "@/features/ai-chat/utils/error-message.ts";
 import { extractServerChatId } from "@/features/ai-chat/utils/adopt-chat-id.ts";
-import { mergeObservedMessage } from "@/features/ai-chat/utils/run-polling.ts";
 import {
   dequeue,
   enqueueMessage,
@@ -87,29 +86,6 @@ interface ChatThreadProps {
    *  Copy/export button available mid-stream). Distinct from onTurnFinished,
    *  which fires only at the terminal outcome. */
   onServerChatId?: (serverChatId?: string) => void;
-  /** #184 reconnect-and-live-follow. When THIS tab reopened a chat whose agent
-   *  run is still going (it is a PASSIVE OBSERVER — it did not start the run here),
-   *  the parent polls the reconnect endpoint and feeds the run's incrementally-
-   *  persisted assistant message here; we merge it into the live list so new
-   *  steps/tool-calls appear as they are persisted. Null when there is nothing to
-   *  observe (no run, feature off, or this tab IS the streamer). The merge is
-   *  ADDITIONALLY guarded by our own `isStreaming`, so a stale value can never
-   *  fight the local stream when we are the streamer. */
-  observedRow?: IAiChatMessageRow | null;
-  /** Report this tab's live streaming status up to the parent, so it can stop
-   *  polling the run while WE are the active streamer (the SSE owns the view) and
-   *  resume once we go idle. Called from an effect on every transition. */
-  onStreamingChange?: (streaming: boolean) => void;
-  /** #184: whether detached/autonomous agent runs are enabled for this workspace.
-   *  When true the Stop button must additionally hit the AUTHORITATIVE server stop
-   *  (via onServerStop) — aborting only the local SSE is just a client disconnect,
-   *  which the server deliberately ignores, so the detached run would keep going. */
-  autonomousRunsEnabled?: boolean;
-  /** #184: request the server-side stop of this chat's active run (the parent owns
-   *  the endpoint call + the "stopping" latch that keeps observer-polling from
-   *  immediately re-streaming the stopping run's output). Called with the resolved
-   *  chat id when the user presses Stop in autonomous mode. */
-  onServerStop?: (chatId: string) => void;
 }
 
 /**
@@ -155,10 +131,6 @@ export default function ChatThread({
   assistantName,
   onTurnFinished,
   onServerChatId,
-  observedRow,
-  onStreamingChange,
-  autonomousRunsEnabled,
-  onServerStop,
 }: ChatThreadProps) {
   const { t } = useTranslation();
 
@@ -244,16 +216,6 @@ export default function ChatThread({
   const flushOnAbortRef = useRef(false);
   const interruptNextSendRef = useRef(false);
 
-  // #234 F5: the user pressed Stop while streaming a BRAND-NEW chat whose server
-  // chat id has not been adopted yet (the `start` chunk carrying it hadn't landed
-  // when Stop was pressed). A local SSE abort alone does NOT stop the DETACHED
-  // autonomous run — it keeps burning tokens and WRITING TO PAGES — so we cannot
-  // just no-op. We latch the stop as PENDING and fire the authoritative server
-  // stop the moment onServerChatId adopts the id (below). Read-and-cleared there;
-  // also defused on every new turn start so it can never fire against a later,
-  // unrelated turn's run.
-  const stopPendingRef = useRef(false);
-
   // FIFO dequeue + send the next queued message (no-op when the queue is empty).
   // Returns whether a message was actually sent, so callers can tell an empty
   // dequeue (nothing to flush) from a real send.
@@ -312,7 +274,7 @@ export default function ChatThread({
     [],
   );
 
-  const { messages, sendMessage, status, stop, error, setMessages } = useChat({
+  const { messages, sendMessage, status, stop, error } = useChat({
     // Stable per-mount key. Existing chats use their real id; new chats use a
     // generated client id (never `undefined`) so the store is NOT re-created on
     // every render mid-stream (see `chatStoreId` above).
@@ -403,14 +365,7 @@ export default function ChatThread({
       return;
     lastForwardedChatIdRef.current = serverChatId;
     onServerChatId(serverChatId);
-    // #234 F5: if Stop was pressed before the id was known, the authoritative
-    // server stop was deferred to this adoption point — fire it now with the
-    // just-adopted id. One-shot (read-and-clear) so it can't fire twice.
-    if (stopPendingRef.current) {
-      stopPendingRef.current = false;
-      onServerStop?.(serverChatId);
-    }
-  }, [messages, onServerChatId, onServerStop]);
+  }, [messages, onServerChatId]);
 
   // Live "turn was interrupted" marker for the CURRENT session. The red error
   // banner (driven by `error`) covers the error case; this covers an aborted
@@ -423,27 +378,6 @@ export default function ChatThread({
 
   const isStreaming = status === "submitted" || status === "streaming";
 
-  // #184: report our live streaming status up so the parent stops polling the run
-  // while WE are the streamer (the SSE owns the view) and resumes once we go idle.
-  // Effect (not render) so it never updates parent state during our own render;
-  // fires on mount with `false`, which also re-syncs the parent after a chat
-  // switch remounts this thread (a fresh mount is idle until the user sends).
-  useEffect(() => {
-    onStreamingChange?.(isStreaming);
-  }, [isStreaming, onStreamingChange]);
-
-  // #184 passive-observer merge: when the parent feeds a polled run message (we
-  // reopened a chat whose run is still going and did NOT start it here), merge it
-  // into the live list so new steps/tool-calls appear as they are persisted. Hard-
-  // gated by `!isStreaming`: if THIS tab is actually the streamer, the local SSE
-  // owns the view and a stale observedRow must never overwrite it. `observedRow`
-  // is a stable per-poll object, so this runs once per poll, not per render.
-  useEffect(() => {
-    if (isStreaming || !observedRow) return;
-    const observed = rowToUiMessage(observedRow);
-    setMessages((prev) => mergeObservedMessage(prev, observed));
-  }, [observedRow, isStreaming, setMessages]);
-
   // "Send now" on a queued message: interrupt the current turn and immediately
   // send THIS message, keeping the agent's partial output. Other queued messages
   // stay queued and flush normally after the new turn. Reuses the existing
@@ -475,40 +409,6 @@ export default function ChatThread({
     [setQueue, stop],
   );
 
-  // Stop the current turn. ALWAYS abort the local SSE (`stop()`) so the composer
-  // returns to idle immediately. In AUTONOMOUS mode the turn is a DETACHED run:
-  // aborting the local SSE is only a client disconnect, which the server ignores,
-  // so the run would keep executing — we ADDITIONALLY request the authoritative
-  // server-side stop (the parent owns that call + the "stopping" latch that keeps
-  // observer-polling from re-streaming the stopping run's output). The chat id is
-  // read live from chatIdRef (adopted early at the stream's `start` chunk); if it
-  // is not known yet — a brand-new chat in the first moment of its first turn —
-  // only the local abort happens (there is no server-side run handle to stop yet).
-  const handleStop = useCallback(() => {
-    stop();
-    if (!autonomousRunsEnabled) return;
-    if (chatIdRef.current) {
-      onServerStop?.(chatIdRef.current);
-    } else {
-      // #234 F5: no chat id yet (brand-new chat in the first moment of its first
-      // turn, before the `start` chunk adopted the id). Latch the stop as pending;
-      // the onServerChatId adoption effect fires the deferred server stop as soon
-      // as the id appears, so the detached run is still authoritatively stopped
-      // instead of left running by a silent local-only abort.
-      //
-      // KNOWN LIMITATION (#234 F5 review): `stop()` above has already aborted the
-      // local SSE reader. In the rare sub-window where Stop is pressed while still
-      // `submitted` (request sent, not one chunk read yet), that abort can cancel
-      // the reader BEFORE the `start` chunk is applied to `messages`, so the
-      // adoption effect never runs and this pending stop never fires. The detached
-      // run then keeps going for that turn. This is not a regression (the pre-fix
-      // behavior sent no server stop at all); closing it fully would require
-      // deferring the local abort until adoption, which is riskier and out of scope
-      // for this fix. Documented so a future change can address the abort-ordering.
-      stopPendingRef.current = true;
-    }
-  }, [stop, autonomousRunsEnabled, onServerStop]);
-
   // Clear the stopped marker as soon as a new turn begins streaming, and drop any
   // stale "Send now" interrupt flags. On the legit interrupt path both refs are
   // already consumed synchronously (onFinish + prepareSendMessagesRequest) before
@@ -520,11 +420,6 @@ export default function ChatThread({
       setStopNotice(null);
       flushOnAbortRef.current = false;
       interruptNextSendRef.current = false;
-      // #234 F5: a new turn is starting — drop any pending deferred-stop from a
-      // previous turn that never adopted an id, so it can never fire against this
-      // (or a later) unrelated turn's run. A deferred stop for the CURRENT turn is
-      // set AFTER this effect (on the Stop click), so this does not clobber it.
-      stopPendingRef.current = false;
     }
   }, [isStreaming]);
 
@@ -644,7 +539,7 @@ export default function ChatThread({
         <ChatInput
           onSend={(text) => sendMessage({ text })}
           onQueue={enqueue}
-          onStop={handleStop}
+          onStop={stop}
           isStreaming={isStreaming}
         />
       </Stack>

apps/client/src/features/ai-chat/queries/ai-chat-query.ts

@@ -12,7 +12,6 @@ import {
   deleteAiChat,
   deleteAiRole,
   getAiChatMessages,
-  getAiChatRun,
   getAiChats,
   getAiRoleCatalog,
   getAiRoleCatalogBundle,
@@ -25,7 +24,6 @@ import {
 import {
   IAiChat,
   IAiChatMessageRow,
-  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -36,7 +34,6 @@ import {
   IAiRoleUpdateFromCatalogResult,
 } from "@/features/ai-chat/types/ai-chat.types.ts";
 import { IPagination } from "@/lib/types.ts";
-import { runPollInterval } from "@/features/ai-chat/utils/run-polling.ts";
 
 export const AI_CHATS_RQ_KEY = ["ai-chats"];
 export const AI_ROLES_RQ_KEY = ["ai-roles"];
@@ -54,18 +51,16 @@ export const AI_CHAT_MESSAGES_RQ_KEY = (chatId: string) => [
   "ai-chat-messages",
   chatId,
 ];
-export const AI_CHAT_RUN_RQ_KEY = (chatId: string) => ["ai-chat-run", chatId];
 
 /** Paginated list of the current user's chats (auto-loads further pages). */
 export function useAiChatsQuery() {
   const query = useInfiniteQuery({
     queryKey: AI_CHATS_RQ_KEY,
-    queryFn: ({ pageParam }) => getAiChats({ cursor: pageParam, limit: 50 }),
+    queryFn: ({ pageParam }) =>
+      getAiChats({ cursor: pageParam, limit: 50 }),
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
-      lastPage.meta.hasNextPage
-        ? (lastPage.meta.nextCursor ?? undefined)
-        : undefined,
+      lastPage.meta.hasNextPage ? (lastPage.meta.nextCursor ?? undefined) : undefined,
   });
 
   const data = useMemo<IPagination<IAiChat> | undefined>(() => {
@@ -95,9 +90,7 @@ export function useAiChatMessagesQuery(chatId: string | undefined) {
       getAiChatMessages({ chatId: chatId as string, cursor: pageParam }),
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
-      lastPage.meta.hasNextPage
-        ? (lastPage.meta.nextCursor ?? undefined)
-        : undefined,
+      lastPage.meta.hasNextPage ? (lastPage.meta.nextCursor ?? undefined) : undefined,
     enabled: !!chatId,
   });
 
@@ -138,34 +131,6 @@ export function useAiChatMessagesQuery(chatId: string | undefined) {
   };
 }
 
-/**
- * Reconnect to a chat's latest agent run and LIVE-FOLLOW it (#184). While the run
- * is active the query re-polls every {@link runPollInterval} ms (driven off the
- * fetched `run.status`, the same status-keyed refetchInterval pattern as the
- * embeddings reindex polling); once the run reaches a terminal status — or there
- * is no run — the interval returns `false` and polling stops on its own. Polling
- * is thus naturally bounded by the run terminating; no separate timeout cap.
- *
- * `enabled` gates the whole thing: callers pass `false` when the autonomous-runs
- * feature is off (the endpoint is NOT flag-gated server-side, but with the feature
- * off the chat has no runs, so polling would only ever return `{ run: null }`) OR
- * when THIS tab is the one actively streaming the run (the live SSE owns the view,
- * so we must not also poll/merge). The global `retry: false` means a failed fetch
- * leaves `data` undefined, so refetchInterval(undefined run) returns false — a
- * failed fetch can never spin a tight loop.
- */
-export function useAiChatRunQuery(
-  chatId: string | undefined,
-  enabled: boolean,
-) {
-  return useQuery<IAiChatRunResponse, Error>({
-    queryKey: AI_CHAT_RUN_RQ_KEY(chatId ?? ""),
-    queryFn: () => getAiChatRun(chatId as string),
-    enabled: !!chatId && enabled,
-    refetchInterval: (query) => runPollInterval(query.state.data?.run),
-  });
-}
-
 export function useRenameAiChatMutation() {
   const queryClient = useQueryClient();
   const { t } = useTranslation();
@@ -315,14 +280,11 @@ export function useImportAiRolesFromCatalogMutation() {
     mutationFn: (payload) => importAiRolesFromCatalog(payload),
     onSuccess: (result) => {
       notifications.show({
-        message: t(
-          "Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}",
-          {
-            created: result.created,
-            renamed: result.renamed,
-            skipped: result.skipped,
-          },
-        ),
+        message: t("Imported {{created}}, renamed {{renamed}}, skipped {{skipped}}", {
+          created: result.created,
+          renamed: result.renamed,
+          skipped: result.skipped,
+        }),
       });
       // Surface partial failures (e.g. unique-name races) as a red warning.
       if (result.errors.length > 0) {

apps/client/src/features/ai-chat/queries/ai-chat-run-query.test.tsx

@@ -1,92 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import React from "react";
-import { renderHook, waitFor } from "@testing-library/react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { IAiChatRunResponse } from "@/features/ai-chat/types/ai-chat.types.ts";
-
-// react-i18next is pulled in transitively by ai-chat-query.ts (the mutation hooks
-// use it); stub it so the module imports cleanly in this hook test.
-vi.mock("react-i18next", () => ({
-  useTranslation: () => ({ t: (key: string) => key }),
-}));
-
-vi.mock("@mantine/notifications", () => ({
-  notifications: { show: vi.fn() },
-}));
-
-// Mock the whole service module; only getAiChatRun is exercised here, but the
-// other named exports must exist so ai-chat-query.ts imports resolve.
-vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
-  getAiChatRun: vi.fn(),
-  getAiChatMessages: vi.fn(),
-  getAiChats: vi.fn(),
-  getAiRoleCatalog: vi.fn(),
-  getAiRoleCatalogBundle: vi.fn(),
-  getAiRoles: vi.fn(),
-  importAiRolesFromCatalog: vi.fn(),
-  createAiRole: vi.fn(),
-  deleteAiChat: vi.fn(),
-  deleteAiRole: vi.fn(),
-  renameAiChat: vi.fn(),
-  updateAiRole: vi.fn(),
-  updateAiRoleFromCatalog: vi.fn(),
-}));
-
-import { getAiChatRun } from "@/features/ai-chat/services/ai-chat-service.ts";
-import { useAiChatRunQuery } from "@/features/ai-chat/queries/ai-chat-query.ts";
-
-function createWrapper() {
-  const queryClient = new QueryClient({
-    defaultOptions: { queries: { retry: false } },
-  });
-  return function Wrapper({ children }: { children: React.ReactNode }) {
-    return (
-      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
-    );
-  };
-}
-
-const runningResponse: IAiChatRunResponse = {
-  run: { id: "run-1", chatId: "c1", status: "running" },
-  message: {
-    id: "a1",
-    role: "assistant",
-    content: "working...",
-    createdAt: "2026-01-01T00:00:00Z",
-  },
-};
-
-describe("useAiChatRunQuery — enable gating", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("fetches the run when enabled (passive observer, feature on)", async () => {
-    vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
-    const { result } = renderHook(() => useAiChatRunQuery("c1", true), {
-      wrapper: createWrapper(),
-    });
-    await waitFor(() => expect(result.current.isSuccess).toBe(true));
-    expect(getAiChatRun).toHaveBeenCalledWith("c1");
-    expect(result.current.data?.run?.status).toBe("running");
-  });
-
-  it("does NOT fetch when disabled (this tab is the streamer / feature off)", async () => {
-    vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
-    renderHook(() => useAiChatRunQuery("c1", false), {
-      wrapper: createWrapper(),
-    });
-    // Give any errant fetch a chance to fire, then assert none did.
-    await new Promise((r) => setTimeout(r, 20));
-    expect(getAiChatRun).not.toHaveBeenCalled();
-  });
-
-  it("does NOT fetch when there is no chat id", async () => {
-    vi.mocked(getAiChatRun).mockResolvedValue(runningResponse);
-    renderHook(() => useAiChatRunQuery(undefined, true), {
-      wrapper: createWrapper(),
-    });
-    await new Promise((r) => setTimeout(r, 20));
-    expect(getAiChatRun).not.toHaveBeenCalled();
-  });
-});

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

@@ -5,7 +5,6 @@ import {
   IAiChatListParams,
   IAiChatMessageRow,
   IAiChatMessagesParams,
-  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -43,38 +42,6 @@ export async function getAiChatMessages(
   return req.data;
 }
 
-/**
- * Reconnect to the latest agent run of a chat (#184). Returns the run's
- * persisted lifecycle state and the assistant message it materializes (the
- * partial output while the run is in-flight, the final output once it finished).
- * The DB is the source of truth, so this works for an in-flight run (the browser
- * dropped, the run kept going) and a finished one alike; `{ run: null }` when the
- * chat has never had a run. Owner-gated server-side (the requesting user must own
- * the chat); it is NOT flag-gated — when the feature is off the chat simply has no
- * runs, so the endpoint returns `{ run: null }`.
- */
-export async function getAiChatRun(
-  chatId: string,
-): Promise<IAiChatRunResponse> {
-  const req = await api.post<IAiChatRunResponse>("/ai-chat/run", { chatId });
-  return req.data;
-}
-
-/**
- * Explicitly STOP the active agent run of a chat (#184). This is the ONLY thing
- * that ends a DETACHED run — a mere browser disconnect (aborting the local SSE)
- * is deliberately ignored server-side, so the client must call this to actually
- * stop an autonomous run. Targeted by `chatId` (the server resolves whatever run
- * is active on it); owner-gated server-side. Returns `{ stopped }` — false when
- * there was nothing active to stop.
- */
-export async function stopRun(
-  chatId: string,
-): Promise<{ stopped: boolean }> {
-  const req = await api.post<{ stopped: boolean }>("/ai-chat/stop", { chatId });
-  return req.data;
-}
-
 /**
  * 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.

apps/client/src/features/ai-chat/types/ai-chat.types.ts

@@ -200,38 +200,6 @@ export interface IAiChatMessageRow {
   createdAt: string;
 }
 
-/**
- * A persisted agent-run row (#184), mirroring the `ai_chat_runs` fields the
- * client reads from `POST /ai-chat/run`. Only `status` is load-bearing for the
- * reconnect-and-live-update UX (it drives the poll cadence); the rest are carried
- * for display/diagnostics. The DB is the source of truth, so this resolves for an
- * in-flight run (the browser dropped, the run kept going) and a finished one.
- */
-export interface IAiChatRun {
-  id: string;
-  chatId: string;
-  // 'pending' | 'running' | 'succeeded' | 'failed' | 'aborted'. The first two are
-  // ACTIVE (keep polling); the rest are TERMINAL (stop polling).
-  status: "pending" | "running" | "succeeded" | "failed" | "aborted" | string;
-  error?: string | null;
-  stepCount?: number;
-  assistantMessageId?: string | null;
-  startedAt?: string | null;
-  finishedAt?: string | null;
-  createdAt?: string;
-  updatedAt?: string;
-}
-
-/**
- * Response of `POST /ai-chat/run` (#184): the latest run of a chat and the
- * assistant message it materializes (the partial/final output, projected from the
- * persisted rows). Both are `null` when the chat has never had a run.
- */
-export interface IAiChatRunResponse {
-  run: IAiChatRun | null;
-  message: IAiChatMessageRow | null;
-}
-
 export interface IAiChatListParams extends QueryParams {}
 
 export interface IAiChatMessagesParams {

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

@@ -1,303 +0,0 @@
-import { describe, it, expect } from "vitest";
-import type { UIMessage } from "@ai-sdk/react";
-import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
-import {
-  RUN_POLL_INTERVAL_MS,
-  isRunActive,
-  runPollInterval,
-  shouldObserveRun,
-  shouldClearStoppingLatch,
-  shouldClearLatchOnQueryError,
-  mergeObservedMessage,
-} from "./run-polling.ts";
-
-function makeRun(status: string): IAiChatRun {
-  return { id: "run-1", chatId: "c1", status };
-}
-
-function makeMsg(id: string, text: string): UIMessage {
-  return {
-    id,
-    role: "assistant",
-    parts: [{ type: "text", text }],
-  } as UIMessage;
-}
-
-describe("isRunActive", () => {
-  it("treats pending and running as active", () => {
-    expect(isRunActive(makeRun("pending"))).toBe(true);
-    expect(isRunActive(makeRun("running"))).toBe(true);
-  });
-
-  it("treats terminal / unknown / nullish as not active", () => {
-    expect(isRunActive(makeRun("succeeded"))).toBe(false);
-    expect(isRunActive(makeRun("failed"))).toBe(false);
-    expect(isRunActive(makeRun("aborted"))).toBe(false);
-    expect(isRunActive(makeRun("weird-future-status"))).toBe(false);
-    expect(isRunActive(null)).toBe(false);
-    expect(isRunActive(undefined)).toBe(false);
-  });
-});
-
-describe("runPollInterval (the refetchInterval helper)", () => {
-  it("returns 2000ms while the run is pending/running", () => {
-    expect(runPollInterval(makeRun("pending"))).toBe(RUN_POLL_INTERVAL_MS);
-    expect(runPollInterval(makeRun("running"))).toBe(RUN_POLL_INTERVAL_MS);
-    expect(RUN_POLL_INTERVAL_MS).toBe(2000);
-  });
-
-  it("returns false (stop polling) once the run is terminal", () => {
-    expect(runPollInterval(makeRun("succeeded"))).toBe(false);
-    expect(runPollInterval(makeRun("failed"))).toBe(false);
-    expect(runPollInterval(makeRun("aborted"))).toBe(false);
-  });
-
-  it("returns false (no polling) when there is no run", () => {
-    expect(runPollInterval(null)).toBe(false);
-    expect(runPollInterval(undefined)).toBe(false);
-  });
-});
-
-describe("shouldObserveRun (observer-vs-streamer decision)", () => {
-  it("observes an active run when this tab is NOT the local streamer", () => {
-    expect(shouldObserveRun(makeRun("running"), false)).toBe(true);
-    expect(shouldObserveRun(makeRun("pending"), false)).toBe(true);
-  });
-
-  it("observes a terminal run too (so the final output shows on reopen)", () => {
-    expect(shouldObserveRun(makeRun("succeeded"), false)).toBe(true);
-  });
-
-  it("does NOT observe when this tab IS the streamer (no double-render)", () => {
-    expect(shouldObserveRun(makeRun("running"), true)).toBe(false);
-    expect(shouldObserveRun(makeRun("succeeded"), true)).toBe(false);
-  });
-
-  it("does NOT observe when there is no run", () => {
-    expect(shouldObserveRun(null, false)).toBe(false);
-    expect(shouldObserveRun(undefined, false)).toBe(false);
-  });
-});
-
-describe("shouldClearStoppingLatch (#234 latch-release decision)", () => {
-  // The one case the latch SHOULD clear: we requested a stop, we are the passive
-  // observer (not streaming), and the CURRENT run is terminal.
-  it("clears only when stopping, observing, and the run is terminal", () => {
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: makeRun("aborted"),
-        isLocalStreaming: false,
-      }),
-    ).toBe(true);
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: makeRun("succeeded"),
-        isLocalStreaming: false,
-      }),
-    ).toBe(true);
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: makeRun("failed"),
-        isLocalStreaming: false,
-      }),
-    ).toBe(true);
-  });
-
-  // Round-3 regression: clearing while THIS tab is still the local streamer would
-  // re-open the flash for the current turn the moment we switch to observer role.
-  // A predicate lacking the streaming gate would (wrongly) return true here.
-  it("does NOT clear while this tab is the local streamer", () => {
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: makeRun("aborted"),
-        isLocalStreaming: true,
-      }),
-    ).toBe(false);
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: makeRun("succeeded"),
-        isLocalStreaming: true,
-      }),
-    ).toBe(false);
-  });
-
-  // The detached run keeps growing after a local abort — while it is still
-  // active the latch MUST hold so the observer merge stays suppressed.
-  it("does NOT clear while the run is still active", () => {
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: makeRun("running"),
-        isLocalStreaming: false,
-      }),
-    ).toBe(false);
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: makeRun("pending"),
-        isLocalStreaming: false,
-      }),
-    ).toBe(false);
-  });
-
-  // #234 F4: on Stop the stale PREVIOUS-turn run is removed from the cache, so the
-  // observed `run` is null until the current turn's run is fetched fresh. A null
-  // run HOLDS the latch — it can never clear against the just-removed stale run,
-  // only against the current turn's own terminal run once observed.
-  it("does NOT clear against a removed/absent run (F4 stale-run guard)", () => {
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: null,
-        isLocalStreaming: false,
-      }),
-    ).toBe(false);
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: true,
-        run: undefined,
-        isLocalStreaming: false,
-      }),
-    ).toBe(false);
-  });
-
-  it("does NOT clear when no stop was requested", () => {
-    expect(
-      shouldClearStoppingLatch({
-        stoppingRun: false,
-        run: makeRun("aborted"),
-        isLocalStreaming: false,
-      }),
-    ).toBe(false);
-  });
-});
-
-describe("shouldClearLatchOnQueryError (#234 F7 error-safety-net decision)", () => {
-  // This guards the REAL anti-flash decision the component's run-query-error
-  // safety-net effect uses (ai-chat-window.tsx wires the effect to THIS helper,
-  // not a copy — so the test is non-vacuous vs the live code).
-
-  // (b) The F7 hole: a TRANSIENT run-query error while `run` is STILL ACTIVE must
-  // NOT clear the latch. TanStack Query v5 retains `data` on error, so
-  // runQueryFailed can be true while the held run is still pending/running.
-  // Against the PRE-F7 condition (without `!isRunActive(run)`) this would return
-  // true — so this assertion fails on the buggy code (non-vacuous).
-  it("does NOT clear on a transient error while the run is still ACTIVE (F7)", () => {
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: true,
-        isLocalStreaming: false,
-        runQueryFailed: true,
-        run: makeRun("running"),
-      }),
-    ).toBe(false);
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: true,
-        isLocalStreaming: false,
-        runQueryFailed: true,
-        run: makeRun("pending"),
-      }),
-    ).toBe(false);
-  });
-
-  // (a) The genuine permanent-null-freeze: run cache cleared by removeQueries +
-  // the refetch keeps ERRORING, so `run === null`. This is the ONLY case the
-  // safety-net exists to cure — it MUST clear so the frozen view resumes.
-  it("clears on a permanent error when the run is null (permanent-null-freeze)", () => {
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: true,
-        isLocalStreaming: false,
-        runQueryFailed: true,
-        run: null,
-      }),
-    ).toBe(true);
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: true,
-        isLocalStreaming: false,
-        runQueryFailed: true,
-        run: undefined,
-      }),
-    ).toBe(true);
-  });
-
-  // A TERMINAL run also satisfies `!isRunActive`; clearing then is harmless — the
-  // terminal effect (shouldClearStoppingLatch) already clears for a terminal run,
-  // so this only ever agrees with it. Asserted so the (c) reasoning is pinned.
-  it("clears on an error when the run is terminal (harmless, agrees with terminal effect)", () => {
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: true,
-        isLocalStreaming: false,
-        runQueryFailed: true,
-        run: makeRun("aborted"),
-      }),
-    ).toBe(true);
-  });
-
-  it("does NOT clear without an actual query error", () => {
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: true,
-        isLocalStreaming: false,
-        runQueryFailed: false,
-        run: null,
-      }),
-    ).toBe(false);
-  });
-
-  it("does NOT clear while this tab is the local streamer", () => {
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: true,
-        isLocalStreaming: true,
-        runQueryFailed: true,
-        run: null,
-      }),
-    ).toBe(false);
-  });
-
-  it("does NOT clear when no stop was requested", () => {
-    expect(
-      shouldClearLatchOnQueryError({
-        stoppingRun: false,
-        isLocalStreaming: false,
-        runQueryFailed: true,
-        run: null,
-      }),
-    ).toBe(false);
-  });
-});
-
-describe("mergeObservedMessage", () => {
-  it("replaces the message with the same id in place (per-step growth)", () => {
-    const prev = [makeMsg("u1", "hi"), makeMsg("a1", "step 1")];
-    const observed = makeMsg("a1", "step 1\nstep 2");
-    const next = mergeObservedMessage(prev, observed);
-    expect(next).toHaveLength(2);
-    expect(next[1]).toBe(observed);
-    expect(next[0]).toBe(prev[0]); // untouched
-    expect(next).not.toBe(prev); // new array (never mutates input)
-  });
-
-  it("appends when the observed message is not yet present", () => {
-    const prev = [makeMsg("u1", "hi")];
-    const observed = makeMsg("a1", "first token");
-    const next = mergeObservedMessage(prev, observed);
-    expect(next).toHaveLength(2);
-    expect(next[1]).toBe(observed);
-  });
-
-  it("returns the original list unchanged when there is nothing to merge", () => {
-    const prev = [makeMsg("u1", "hi")];
-    expect(mergeObservedMessage(prev, null)).toBe(prev);
-    expect(mergeObservedMessage(prev, undefined)).toBe(prev);
-  });
-});

apps/client/src/features/ai-chat/utils/run-polling.ts

@@ -1,151 +0,0 @@
-import type { UIMessage } from "@ai-sdk/react";
-import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
-
-/**
- * Reconnect-and-live-follow helpers (#184). When a chat is reopened while its
- * agent run is STILL going, this tab is a PASSIVE OBSERVER: it did not start the
- * run here (no local SSE stream), so it catches up by POLLING the reconnect
- * endpoint (`POST /ai-chat/run`) and merging the run's incrementally-persisted
- * assistant message into the rendered thread. These are the small pure decisions
- * that machinery hangs off, extracted so they can be unit-tested in isolation
- * (mirrors how reindex polling / editor-sync-state are tested).
- */
-
-/** How often to re-poll the reconnect endpoint while a run is ACTIVE. */
-export const RUN_POLL_INTERVAL_MS = 2000;
-
-// 'pending' and 'running' are the two ACTIVE statuses; 'succeeded' | 'failed' |
-// 'aborted' are TERMINAL (and any unknown future status is treated as terminal,
-// so a stale/odd value never polls forever).
-const ACTIVE_STATUSES = new Set(["pending", "running"]);
-
-/** Whether a run is still going (worth polling / merging live updates from). */
-export function isRunActive(run: IAiChatRun | null | undefined): boolean {
-  return !!run && ACTIVE_STATUSES.has(run.status);
-}
-
-/**
- * The TanStack Query `refetchInterval` value for the run query: poll every
- * {@link RUN_POLL_INTERVAL_MS} while the run is active, and `false` (stop) once
- * it is terminal or there is no run. Polling is thus naturally bounded by the run
- * reaching a terminal status — no separate timeout cap is needed.
- */
-export function runPollInterval(
-  run: IAiChatRun | null | undefined,
-): number | false {
-  return isRunActive(run) ? RUN_POLL_INTERVAL_MS : false;
-}
-
-/**
- * Observer-vs-streamer decision. We render the polled run message (catch up +
- * keep advancing) ONLY when this tab is a passive observer: there IS a run AND
- * this tab is NOT the one locally streaming it (we reconnected, we didn't start
- * it here). When this tab is the streamer, the live SSE stream owns the view, so
- * we neither poll nor merge — avoiding a double-render fight. Terminal runs still
- * merge (so the final persisted output is shown on reopen); the poll itself is
- * stopped separately by {@link runPollInterval}.
- */
-export function shouldObserveRun(
-  run: IAiChatRun | null | undefined,
-  localStreaming: boolean,
-): boolean {
-  return !!run && !localStreaming;
-}
-
-/**
- * Should the "stopping" latch — which suppresses the observer re-stream flash
- * after the user pressed Stop — be RELEASED now? All three must hold:
- *  - `stoppingRun`: we actually requested a stop (otherwise nothing to release);
- *  - `!isLocalStreaming`: this tab is NOT the local streamer. While we are the
- *    streamer the run query is disabled, so the observed `run` is not the run we
- *    are following — releasing the latch then would re-open the flash for the
- *    current turn the instant we switch to observer role;
- *  - the observed `run` EXISTS and has reached a TERMINAL status.
- *
- * The null / still-active `run` case is the #234 F4 invariant. On Stop the stale
- * PREVIOUS-turn run is removed from the query cache (`removeQueries`), so `run`
- * is null until the CURRENT turn's run is re-fetched fresh; a null or active run
- * therefore HOLDS the latch, so it can only ever clear against the current turn's
- * OWN terminal run — never a stale cached one. (The cache removal itself is
- * integration-level in AiChatWindow; this predicate encodes the decision given
- * whatever run is currently observed, and a stale terminal run is
- * indistinguishable from a current terminal run at the predicate level — hence
- * the cache removal is what guarantees only the current run is ever passed here.)
- */
-export function shouldClearStoppingLatch(args: {
-  stoppingRun: boolean;
-  run: IAiChatRun | null | undefined;
-  isLocalStreaming: boolean;
-}): boolean {
-  const { stoppingRun, run, isLocalStreaming } = args;
-  if (!stoppingRun || isLocalStreaming) return false;
-  return !!run && !isRunActive(run);
-}
-
-/**
- * Should the "stopping" latch be RELEASED by the run-query ERROR safety-net?
- * (#234 F7 — a NEW path of the same re-stream flash the F4 latch exists to
- * prevent.) After Stop, `handleServerStop` clears the run cache; the terminal
- * effect then holds the latch via `if (!run) return` until the CURRENT turn's run
- * is fetched fresh. If that refetch instead ERRORS permanently, `run` stays null,
- * its status-keyed refetchInterval is off, and nothing would ever observe a
- * terminal run — freezing the view with the observer merge suppressed. This
- * safety-net cures ONLY that genuine permanent-null-freeze.
- *
- * All four must hold:
- *  - `stoppingRun`: we actually requested a stop (otherwise nothing to release);
- *  - `!isLocalStreaming`: this tab is NOT the local streamer (same reason as
- *    {@link shouldClearStoppingLatch});
- *  - `runQueryFailed`: the run query is in its error state (TanStack Query v5 with
- *    retry:false — isError);
- *  - `!isRunActive(run)`: the observed `run` is NOT an active (pending/running)
- *    held run. This is the F7 gate. In TanStack Query v5 the query's `data` is
- *    RETAINED on error, so `runQueryFailed` can be true while `run` is STILL an
- *    ACTIVE run (a single transient GET-run failure in the window between Stop and
- *    settle). Without this gate a transient error would release the latch early —
- *    re-opening the observer merge and flashing the growing detached run over the
- *    frozen row (exactly the F4 flash). Gating on the run NOT being active means we
- *    only ever cure the permanent-null-freeze (`run === null`, so
- *    `isRunActive(null)` is false), never release against an active run.
- *
- * (A terminal `run` also satisfies `!isRunActive(run)`; clearing then is harmless
- * — the terminal effect's {@link shouldClearStoppingLatch} already clears the
- * latch for a terminal run, so this only ever agrees with it, never conflicts.)
- *
- * INVARIANT (do not break): clearing the latch on the `run === null` branch is safe
- * ONLY because the run query's `refetchInterval` (see {@link runPollInterval}) stops
- * polling when the data is empty — so after we clear on null+error there is no
- * subsequent auto-poll that could return a still-active detached run and re-open the
- * merge. If `refetchInterval` is ever changed to keep polling on `run === null`/on
- * error, this null-branch clear would re-open the F7 flash through the null path.
- * Do not change the run query's refetchInterval without re-checking this path.
- */
-export function shouldClearLatchOnQueryError(args: {
-  stoppingRun: boolean;
-  isLocalStreaming: boolean;
-  runQueryFailed: boolean;
-  run: IAiChatRun | null | undefined;
-}): boolean {
-  const { stoppingRun, isLocalStreaming, runQueryFailed, run } = args;
-  return (
-    stoppingRun && !isLocalStreaming && runQueryFailed && !isRunActive(run)
-  );
-}
-
-/**
- * Merge an observed assistant message into the rendered list: replace the message
- * with the same id in place (the in-progress assistant row is already seeded from
- * history, so per-step growth replaces it), or append it when absent. Returns a
- * new array; the input is never mutated.
- */
-export function mergeObservedMessage(
-  messages: UIMessage[],
-  observed: UIMessage | null | undefined,
-): UIMessage[] {
-  if (!observed) return messages;
-  const idx = messages.findIndex((m) => m.id === observed.id);
-  if (idx === -1) return [...messages, observed];
-  const next = messages.slice();
-  next[idx] = observed;
-  return next;
-}

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

@@ -40,20 +40,50 @@ function renderItem(comment: IComment) {
   );
 }
 
-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).
 });

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 { 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";
@@ -119,24 +119,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>
 

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,11 @@ export interface IComment {
   createdSource?: string;
   aiChatId?: string | null;
   resolvedSource?: 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/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

@@ -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(() => {

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}`;
 }
@@ -48,32 +61,41 @@ function writeStorage(pageId: string, scrollY: number): void {
  * 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 +136,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 +188,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 +198,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 +225,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 +244,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/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

@@ -78,7 +78,7 @@ 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 { 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";
@@ -143,7 +143,6 @@ export default function PageEditor({
     [isComponentMounted],
   );
   const { handleScrollTo } = useEditorScroll({ canScroll });
-  const { restoreScrollPosition } = useScrollPosition(pageId);
   // Providers only created once per pageId
   const providersRef = useRef<{
     local: IndexeddbPersistence;
@@ -482,10 +481,10 @@ export default function PageEditor({
     }
   }, [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>

apps/client/src/features/editor/styles/media.css

@@ -71,3 +71,22 @@
   }
 }
 
+/* Inline image rows (#284): center the anonymous line boxes formed by
+   consecutive [data-image-align="inline"] node-view containers. A row has no
+   DOM wrapper of its own, so its horizontal placement is controlled by the
+   text-align of the nearest block ancestor (the editor root or a nested
+   block container: blockquote, callout, list item, table cell, details).
+   Centering is enabled only in containers that actually hold an inline
+   image (:has), and every other child of such a container gets its default
+   alignment back so ordinary text is unaffected. Explicit per-block
+   alignment from the toolbar is an inline style and still wins. Browsers
+   without :has() degrade to left-pinned rows. */
+.ProseMirror:has(> [data-image-align="inline"]),
+.ProseMirror :has(> [data-image-align="inline"]) {
+  text-align: center;
+}
+
+.ProseMirror:has(> [data-image-align="inline"]) > :not([data-image-align="inline"]),
+.ProseMirror :has(> [data-image-align="inline"]) > :not([data-image-align="inline"]) {
+  text-align: start;
+}

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/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/features/workspace/components/settings/components/ai-provider-settings.tsx

@@ -394,10 +394,6 @@ export default function AiProviderSettings() {
     useState<boolean>(
       workspace?.settings?.ai?.publicShareAssistant ?? false,
     );
-  // #184: detached/autonomous agent runs (settings.ai.autonomousRuns).
-  const [autonomousRunsEnabled, setAutonomousRunsEnabled] = useState<boolean>(
-    workspace?.settings?.ai?.autonomousRuns ?? false,
-  );
   const [chatToggleLoading, setChatToggleLoading] = useState(false);
   const [searchToggleLoading, setSearchToggleLoading] = useState(false);
   const [dictationToggleLoading, setDictationToggleLoading] = useState(false);
@@ -407,8 +403,6 @@ export default function AiProviderSettings() {
     publicShareAssistantToggleLoading,
     setPublicShareAssistantToggleLoading,
   ] = useState(false);
-  const [autonomousRunsToggleLoading, setAutonomousRunsToggleLoading] =
-    useState(false);
 
   // Whether a key is currently stored server-side (drives the placeholder).
   const [hasApiKey, setHasApiKey] = useState(false);
@@ -736,37 +730,6 @@ export default function AiProviderSettings() {
     }
   }
 
-  // Optimistic toggle for detached/autonomous agent runs
-  // (settings.ai.autonomousRuns). When on, a chat turn becomes a server-side run
-  // that survives a browser disconnect and can be reconnected to / live-followed;
-  // only an explicit Stop ends it. Off by default; single-instance-only in phase 1.
-  async function handleToggleAutonomousRuns(value: boolean) {
-    setAutonomousRunsToggleLoading(true);
-    const previous = autonomousRunsEnabled;
-    setAutonomousRunsEnabled(value);
-    try {
-      const updated = await updateWorkspace({ autonomousRuns: value });
-      setWorkspace({
-        ...updated,
-        settings: {
-          ...updated.settings,
-          ai: { ...updated.settings?.ai, autonomousRuns: value },
-        },
-      });
-      notifications.show({ message: t("Updated successfully") });
-    } catch (err) {
-      setAutonomousRunsEnabled(previous);
-      const message = (err as { response?: { data?: { message?: string } } })
-        ?.response?.data?.message;
-      notifications.show({
-        message: message ?? t("Failed to update data"),
-        color: "red",
-      });
-    } finally {
-      setAutonomousRunsToggleLoading(false);
-    }
-  }
-
   // Admins only — match the previous behavior.
   if (!isAdmin) {
     return (
@@ -997,31 +960,6 @@ export default function AiProviderSettings() {
           {...form.getInputProps("publicShareAssistantRoleId")}
         />
 
-        {/* Detached/autonomous agent runs: a chat turn becomes a server-side run
-            that survives a browser disconnect; only an explicit Stop ends it.
-            Single-instance-only in phase 1. */}
-        <Group justify="space-between" align="center" wrap="nowrap" mt="md">
-          <Stack gap={0}>
-            <Text fw={600} size="sm">
-              {t("Autonomous agent runs")}
-            </Text>
-            <Text size="xs" c="dimmed">
-              {t(
-                "Keep an agent turn running server-side even if the browser disconnects; reconnect and follow it on reopen. Single-instance deployments only.",
-              )}
-            </Text>
-          </Stack>
-          <Switch
-            label={t("Enabled")}
-            labelPosition="left"
-            checked={autonomousRunsEnabled}
-            disabled={autonomousRunsToggleLoading}
-            onChange={(e) =>
-              handleToggleAutonomousRuns(e.currentTarget.checked)
-            }
-          />
-        </Group>
-
         <Group mt="md" align="center">
           <Button
             variant="default"

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

@@ -26,9 +26,6 @@ export interface IWorkspace {
   aiDictation?: boolean;
   aiDictationStreaming?: boolean;
   aiPublicShareAssistant?: boolean;
-  // Write-only field for updateWorkspace({ autonomousRuns }). Read state lives at
-  // settings.ai.autonomousRuns.
-  autonomousRuns?: boolean;
   trashRetentionDays?: number;
   // Default lifetime (HOURS) for new temporary notes; frozen per-note at creation.
   temporaryNoteHours?: number;
@@ -68,9 +65,6 @@ export interface IWorkspaceAiSettings {
   dictation?: boolean;
   dictationStreaming?: boolean;
   publicShareAssistant?: boolean;
-  // #184: detached agent runs (a run survives a browser disconnect and can be
-  // reconnected to / live-followed on reopen). Gates the run-reconnect polling.
-  autonomousRuns?: boolean;
 }
 
 export interface IWorkspaceSharingSettings {

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/core/ai-chat/ai-chat-run.service.spec.ts

@@ -1,527 +0,0 @@
-import { Logger } from '@nestjs/common';
-import {
-  AiChatRunService,
-  RunAlreadyActiveError,
-  ONE_ACTIVE_RUN_PER_CHAT_INDEX,
-  mapTurnStatusToRun,
-} from './ai-chat-run.service';
-
-/** Shape a Postgres unique-violation the way the postgres.js driver surfaces it:
- *  SQLSTATE 23505 + the offending index in `constraint_name`. */
-function uniqueViolation(constraintName: string): Error & {
-  code: string;
-  constraint_name: string;
-} {
-  return Object.assign(
-    new Error('duplicate key value violates unique constraint'),
-    {
-      code: '23505',
-      constraint_name: constraintName,
-    },
-  );
-}
-
-/**
- * Unit coverage for the #184 phase-1 run lifecycle (AiChatRunService) with a
- * hand-rolled mock repo — no Nest graph, no DB. The invariant under test is the
- * one that makes a run "autonomous": a run keeps going when its SUBSCRIBER (the
- * browser) detaches, and ONLY an explicit stop aborts it. We assert that at the
- * abort-signal level (the signal the agent loop actually consumes).
- */
-
-/** Minimal EnvironmentService stub. Single-instance (CLOUD unset) by default. */
-function makeEnv(isCloud = false) {
-  return { isCloud: () => isCloud };
-}
-
-function makeRepo(overrides: Record<string, jest.Mock> = {}) {
-  return {
-    insert: jest.fn(async (v: any) => ({
-      id: 'run-1',
-      status: v.status ?? 'running',
-      chatId: v.chatId,
-      workspaceId: v.workspaceId,
-    })),
-    update: jest.fn(async () => ({ id: 'run-1' })),
-    markStopRequested: jest.fn(async () => ({ id: 'run-1' })),
-    findActiveByChat: jest.fn(async () => undefined),
-    findLatestByChat: jest.fn(async () => undefined),
-    findById: jest.fn(async () => undefined),
-    sweepRunning: jest.fn(async () => 0),
-    ...overrides,
-  };
-}
-
-describe('mapTurnStatusToRun', () => {
-  it('maps the turn terminal status to the run terminal status', () => {
-    expect(mapTurnStatusToRun('completed')).toBe('succeeded');
-    expect(mapTurnStatusToRun('error')).toBe('failed');
-    expect(mapTurnStatusToRun('aborted')).toBe('aborted');
-  });
-});
-
-describe('AiChatRunService.onModuleInit (startup sweep)', () => {
-  afterEach(() => jest.restoreAllMocks());
-
-  it('calls sweepRunning and resolves; logs when > 0', async () => {
-    const repo = makeRepo({ sweepRunning: jest.fn(async () => 2) });
-    const logSpy = jest
-      .spyOn(Logger.prototype, 'log')
-      .mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await expect(svc.onModuleInit()).resolves.toBeUndefined();
-    expect(repo.sweepRunning).toHaveBeenCalledTimes(1);
-    expect(logSpy).toHaveBeenCalledTimes(1);
-    expect(String(logSpy.mock.calls[0][0])).toContain('2');
-  });
-
-  it('a sweep failure is swallowed (never blocks startup)', async () => {
-    const repo = makeRepo({
-      sweepRunning: jest.fn(async () => {
-        throw new Error('db down');
-      }),
-    });
-    const warnSpy = jest
-      .spyOn(Logger.prototype, 'warn')
-      .mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await expect(svc.onModuleInit()).resolves.toBeUndefined();
-    // The first warn is the sweep failure (the multi-instance warn never fires
-    // single-instance), so the message is the db error.
-    expect(String(warnSpy.mock.calls[0][0])).toContain('db down');
-  });
-
-  it('F1 (DECISION C): the boot sweep is UNCONDITIONAL — sweepRunning is called with NO staleness window, so a fresh running run (updatedAt = now) is settled, not skipped', async () => {
-    // The bug: a fast restart (deploy/OOM within minutes of the last step) left a
-    // run stuck 'running' under the old 10-min window, 409ing every later turn in
-    // the chat. The fix settles ALL pending|running on boot. We assert the service
-    // invokes sweepRunning with no `staleMs` (the unconditional path); the repo's
-    // own spec proves no-window => no updatedAt filter.
-    const repo = makeRepo({ sweepRunning: jest.fn(async () => 1) });
-    jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await svc.onModuleInit();
-    expect(repo.sweepRunning).toHaveBeenCalledTimes(1);
-    const callArgs = repo.sweepRunning.mock.calls[0] as unknown[];
-    const firstArg = callArgs[0] as { staleMs?: number } | undefined;
-    // Either no opts at all, or opts without a staleMs window => unconditional.
-    expect(firstArg?.staleMs).toBeUndefined();
-  });
-
-  it('F2 (DECISION A): warns at startup that autonomousRuns is single-instance-only when a horizontally-scaled deployment (CLOUD) is detected', async () => {
-    const repo = makeRepo();
-    const warnSpy = jest
-      .spyOn(Logger.prototype, 'warn')
-      .mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv(true) as never);
-    await svc.onModuleInit();
-    const warned = warnSpy.mock.calls.some((c) =>
-      /single-instance-only/i.test(String(c[0])),
-    );
-    expect(warned).toBe(true);
-  });
-
-  it('F2: does NOT warn about multi-instance on a single-instance (CLOUD unset) deployment', async () => {
-    const repo = makeRepo();
-    const warnSpy = jest
-      .spyOn(Logger.prototype, 'warn')
-      .mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv(false) as never);
-    await svc.onModuleInit();
-    const warned = warnSpy.mock.calls.some((c) =>
-      /single-instance-only/i.test(String(c[0])),
-    );
-    expect(warned).toBe(false);
-  });
-});
-
-describe('AiChatRunService run lifecycle', () => {
-  it('beginRun inserts a running row and registers a live abort controller', async () => {
-    const repo = makeRepo();
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    const handle = await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-    expect(repo.insert).toHaveBeenCalledWith(
-      expect.objectContaining({
-        chatId: 'chat-1',
-        workspaceId: 'ws-1',
-        createdBy: 'user-1',
-        status: 'running',
-        trigger: 'user',
-      }),
-    );
-    expect(handle.runId).toBe('run-1');
-    expect(handle.signal.aborted).toBe(false);
-    expect(svc.isLocallyActive('run-1')).toBe(true);
-  });
-
-  it('beginRun REJECTS the racer: a 23505 on the one-active-per-chat index throws RunAlreadyActiveError (not swallowed) and registers no controller', async () => {
-    // The race: the controller's cheap pre-check passed for BOTH concurrent
-    // turns, so the loser's INSERT hits the partial unique index. That rejection
-    // is the authoritative gate — it must surface, not be swallowed into an
-    // untracked turn.
-    const repo = makeRepo({
-      insert: jest.fn(async () => {
-        throw uniqueViolation(ONE_ACTIVE_RUN_PER_CHAT_INDEX);
-      }),
-    });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await expect(
-      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
-    ).rejects.toBeInstanceOf(RunAlreadyActiveError);
-    // No controller leaked for a rejected start.
-    expect(svc.isLocallyActive('run-1')).toBe(false);
-  });
-
-  it('beginRun does NOT mask an unrelated unique violation as already-active', async () => {
-    // A 23505 on some OTHER constraint is a real bug, not the race — it must
-    // propagate unchanged so it is never silently treated as "already active".
-    const other = uniqueViolation('ai_chat_runs_pkey');
-    const repo = makeRepo({
-      insert: jest.fn(async () => {
-        throw other;
-      }),
-    });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await expect(
-      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
-    ).rejects.toBe(other);
-  });
-
-  it('beginRun propagates a non-unique insert failure unchanged', async () => {
-    const boom = new Error('connection reset');
-    const repo = makeRepo({
-      insert: jest.fn(async () => {
-        throw boom;
-      }),
-    });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await expect(
-      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
-    ).rejects.toBe(boom);
-  });
-
-  it('two concurrent begins on one chat: exactly one wins, the other is rejected as already-active', async () => {
-    // Integration-style: model the DB partial unique index with a one-shot slot.
-    // The first insert claims it; the second hits a 23505 on the active index.
-    let slotTaken = false;
-    const repo = makeRepo({
-      insert: jest.fn(async (v: any) => {
-        if (slotTaken) throw uniqueViolation(ONE_ACTIVE_RUN_PER_CHAT_INDEX);
-        slotTaken = true;
-        return { id: 'run-win', status: v.status, chatId: v.chatId };
-      }),
-    });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    const results = await Promise.allSettled([
-      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
-      svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'user-1' }),
-    ]);
-    const fulfilled = results.filter((r) => r.status === 'fulfilled');
-    const rejected = results.filter((r) => r.status === 'rejected');
-    expect(fulfilled).toHaveLength(1);
-    expect(rejected).toHaveLength(1);
-    expect((rejected[0] as PromiseRejectedResult).reason).toBeInstanceOf(
-      RunAlreadyActiveError,
-    );
-    // Exactly the winner is locally active.
-    expect(svc.isLocallyActive('run-win')).toBe(true);
-  });
-
-  it('a SUBSCRIBER detaching does NOT abort the run (only an explicit stop does)', async () => {
-    const repo = makeRepo();
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    const handle = await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-    // Model a browser disconnect: nothing in the run service is told to stop.
-    // The signal the agent loop consumes must stay un-aborted and the run stays
-    // locally active — i.e. it keeps running server-side.
-    expect(handle.signal.aborted).toBe(false);
-    expect(svc.isLocallyActive('run-1')).toBe(true);
-    // markStopRequested was never called by a mere detach.
-    expect(repo.markStopRequested).not.toHaveBeenCalled();
-  });
-
-  it('requestStop aborts the live controller, marks the row, and reports true', async () => {
-    const repo = makeRepo();
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    const handle = await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-    const aborted = jest.fn();
-    handle.signal.addEventListener('abort', aborted);
-
-    const result = await svc.requestStop('run-1', 'ws-1');
-
-    expect(result).toBe(true);
-    expect(handle.signal.aborted).toBe(true);
-    expect(aborted).toHaveBeenCalledTimes(1);
-    expect(repo.markStopRequested).toHaveBeenCalledWith('run-1', 'ws-1');
-  });
-
-  it('requestStop on a run this replica does NOT hold still marks the row (true)', async () => {
-    // e.g. after a restart, or a sibling replica owns the controller. The row is
-    // marked so the owning replica/sweep settles it; we report a stop took effect.
-    const repo = makeRepo({
-      markStopRequested: jest.fn(async () => ({ id: 'run-9' })),
-    });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    const result = await svc.requestStop('run-9', 'ws-1');
-    expect(result).toBe(true);
-    expect(svc.isLocallyActive('run-9')).toBe(false);
-  });
-
-  it('requestStop still aborts the live controller when markStopRequested rejects (transient DB error)', async () => {
-    // F15: the in-memory abort is the ONLY thing that stops a run and must not be
-    // hostage to the audit write of stop_requested_at. A transient failure on
-    // markStopRequested must NOT prevent abort() nor make requestStop throw.
-    const warnSpy = jest
-      .spyOn(Logger.prototype, 'warn')
-      .mockImplementation(() => undefined);
-    const repo = makeRepo({
-      markStopRequested: jest.fn(async () => {
-        throw new Error('pool exhausted');
-      }),
-    });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    const handle = await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-    const aborted = jest.fn();
-    handle.signal.addEventListener('abort', aborted);
-
-    // Does NOT throw despite the DB write rejecting.
-    const result = await svc.requestStop('run-1', 'ws-1');
-
-    // The live turn was aborted even though the audit write failed...
-    expect(handle.signal.aborted).toBe(true);
-    expect(aborted).toHaveBeenCalledTimes(1);
-    expect(repo.markStopRequested).toHaveBeenCalledWith('run-1', 'ws-1');
-    // ...the catch branch logged the swallowed failure...
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    // ...and a stop is reported as having taken effect (the entry existed).
-    expect(result).toBe(true);
-    warnSpy.mockRestore();
-  });
-
-  it('requestStop on an already-settled run (nothing active) reports false', async () => {
-    const repo = makeRepo({
-      markStopRequested: jest.fn(async () => undefined),
-    });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    const result = await svc.requestStop('run-done', 'ws-1');
-    expect(result).toBe(false);
-  });
-
-  it('finalizeRun settles the row to the mapped status with finishedAt and drops the in-memory entry', async () => {
-    const repo = makeRepo();
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-    expect(svc.isLocallyActive('run-1')).toBe(true);
-
-    await svc.finalizeRun('run-1', 'ws-1', 'error', 'provider blew up');
-
-    expect(svc.isLocallyActive('run-1')).toBe(false);
-    expect(repo.update).toHaveBeenCalledWith(
-      'run-1',
-      'ws-1',
-      expect.objectContaining({
-        status: 'failed',
-        error: 'provider blew up',
-        finishedAt: expect.any(Date),
-      }),
-    );
-  });
-
-  it('finalizeRun is IDEMPOTENT: a second settle no-ops (single terminal write)', async () => {
-    // The #184 review fix: AiChatService.stream wraps the turn in a safety-net
-    // catch that settles a failed turn AND streamText's terminal callback may
-    // also settle — both routes call finalizeRun. Only the FIRST may write the
-    // terminal row; the second must no-op so a late settle can never clobber the
-    // real terminal status or double-write the row.
-    const repo = makeRepo();
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-
-    await svc.finalizeRun('run-1', 'ws-1', 'error', 'first');
-    expect(svc.isLocallyActive('run-1')).toBe(false);
-    // A second settle (e.g. a streamText callback firing after the catch) no-ops.
-    await svc.finalizeRun('run-1', 'ws-1', 'completed', undefined);
-
-    expect(repo.update).toHaveBeenCalledTimes(1);
-    expect(repo.update).toHaveBeenCalledWith(
-      'run-1',
-      'ws-1',
-      expect.objectContaining({ status: 'failed', error: 'first' }),
-    );
-  });
-
-  it('CONCURRENCY: two simultaneous finalizeRun on the same run write the terminal row EXACTLY ONCE (the 2nd caller exits synchronously at the atomic claim)', async () => {
-    // The CRITICAL race: AiChatService.stream's safety-net catch settles the turn
-    // to 'error' while a streamText terminal callback also settles it — both call
-    // finalizeRun for the SAME runId. The once-gate must close ATOMICALLY: a
-    // `settled.has` check alone is read BEFORE the awaited UPDATE, so both callers
-    // would pass it and BOTH write the row (last-write-wins clobber + double
-    // write). The fix claims the run with a SYNCHRONOUS `active.delete` before any
-    // await, so the second caller returns in the same tick, before the UPDATE.
-    //
-    // We force the two calls to overlap by making `update` return a promise we
-    // resolve only AFTER both finalizeRun calls have run their synchronous bodies.
-    let resolveUpdate!: (v: unknown) => void;
-    const updateGate = new Promise((res) => {
-      resolveUpdate = res;
-    });
-    const update = jest.fn(() => updateGate);
-    const repo = makeRepo({ update });
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-
-    // Fire both before the (pending) update resolves. The first synchronously
-    // claims the entry (active.delete) and awaits update; the second, started in
-    // the same macrotask, finds the entry already gone and returns at the claim
-    // WITHOUT ever calling update.
-    const p1 = svc.finalizeRun('run-1', 'ws-1', 'completed');
-    const p2 = svc.finalizeRun('run-1', 'ws-1', 'error', 'safety-net');
-
-    // The decisive assertion: exactly one caller reached the terminal UPDATE.
-    expect(update).toHaveBeenCalledTimes(1);
-
-    // Let the single in-flight update land; both calls resolve cleanly.
-    resolveUpdate({ id: 'run-1' });
-    await Promise.all([p1, p2]);
-
-    expect(update).toHaveBeenCalledTimes(1);
-    // The winner is the FIRST caller ('completed' -> 'succeeded'); the late
-    // 'error' settle never wrote, so it could not clobber the real status.
-    expect(update).toHaveBeenCalledWith(
-      'run-1',
-      'ws-1',
-      expect.objectContaining({ status: 'succeeded' }),
-    );
-    expect(svc.isLocallyActive('run-1')).toBe(false);
-  });
-
-  it('F6: a TRANSIENT terminal-write failure is ridden out by the bounded retry — the run is settled, not stranded', async () => {
-    // The bug: finalizeRun used to DROP the in-memory entry BEFORE the terminal
-    // UPDATE, then only warn-log a failure. A single transient blip (pool
-    // exhaustion / deadlock / connection hiccup) on that PK UPDATE left the row
-    // 'running' with nothing left to recover it -> every later turn in that chat
-    // 409s until a restart. The fix updates FIRST and retries.
-    let calls = 0;
-    const repo = makeRepo({
-      update: jest.fn(async () => {
-        calls += 1;
-        if (calls === 1) throw new Error('deadlock detected');
-        return { id: 'run-1' };
-      }),
-    });
-    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-
-    await svc.finalizeRun('run-1', 'ws-1', 'completed');
-
-    // The retry landed the terminal write: the entry is dropped (slot freed) and
-    // the row carries the real terminal status — NOT stranded at 'running'.
-    expect(svc.isLocallyActive('run-1')).toBe(false);
-    expect(repo.update).toHaveBeenCalledTimes(2);
-    expect(repo.update).toHaveBeenLastCalledWith(
-      'run-1',
-      'ws-1',
-      expect.objectContaining({ status: 'succeeded' }),
-    );
-  });
-
-  it('F6: if the terminal write keeps failing, the entry is RETAINED and a LATER settle completes it (chat not permanently 409d)', async () => {
-    // Worst case: the DB is down for the whole first finalize (all attempts fail).
-    // The run must NOT be silently lost — the entry stays so a subsequent settle
-    // (a streamText callback, requestStop -> onAbort, or a future sweep) can retry.
-    let healthy = false;
-    const repo = makeRepo({
-      update: jest.fn(async () => {
-        if (!healthy) throw new Error('pool exhausted');
-        return { id: 'run-1' };
-      }),
-    });
-    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
-    const errorSpy = jest
-      .spyOn(Logger.prototype, 'error')
-      .mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await svc.beginRun({
-      chatId: 'chat-1',
-      workspaceId: 'ws-1',
-      userId: 'user-1',
-    });
-
-    // First settle: every bounded attempt fails -> entry retained, NOT settled.
-    await svc.finalizeRun('run-1', 'ws-1', 'completed');
-    expect(svc.isLocallyActive('run-1')).toBe(true);
-    // F12: the give-up emits ONE explicit, greppable ERROR (run + chat context)
-    // so an operator can tell "gave up, run held in memory" from a per-attempt
-    // blip — distinct from the per-attempt warns.
-    const gaveUp = errorSpy.mock.calls.some(
-      (c) =>
-        /NON-TERMINAL/.test(String(c[0])) &&
-        /run-1/.test(String(c[0])) &&
-        /chat-1/.test(String(c[0])),
-    );
-    expect(gaveUp).toBe(true);
-
-    // The DB recovers; a later settle now succeeds and frees the slot.
-    healthy = true;
-    await svc.finalizeRun('run-1', 'ws-1', 'completed');
-    expect(svc.isLocallyActive('run-1')).toBe(false);
-    expect(repo.update).toHaveBeenLastCalledWith(
-      'run-1',
-      'ws-1',
-      expect.objectContaining({ status: 'succeeded' }),
-    );
-
-    // And it is now idempotent: a further settle no-ops (terminal row already
-    // written), so a double-settle can never clobber the real status.
-    const callsBefore = repo.update.mock.calls.length;
-    await svc.finalizeRun('run-1', 'ws-1', 'error', 'late');
-    expect(repo.update).toHaveBeenCalledTimes(callsBefore);
-  });
-
-  it('recordStep / linkAssistantMessage are best-effort: a repo failure is swallowed', async () => {
-    const repo = makeRepo({
-      update: jest.fn(async () => {
-        throw new Error('transient');
-      }),
-    });
-    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
-    const svc = new AiChatRunService(repo as never, makeEnv() as never);
-    await expect(svc.recordStep('run-1', 'ws-1', 3)).resolves.toBeUndefined();
-    await expect(
-      svc.linkAssistantMessage('run-1', 'ws-1', 'msg-1'),
-    ).resolves.toBeUndefined();
-  });
-});

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

@@ -1,452 +0,0 @@
-import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
-import { AiChatRunRepo } from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
-import { AiChatRun } from '@docmost/db/types/entity.types';
-import { isUniqueViolation, violatedConstraint } from '@docmost/db/utils';
-import { EnvironmentService } from '../../integrations/environment/environment.service';
-
-/** Name of the partial unique index enforcing "one active run per chat" (see the
- *  ai_chat_runs migration). A 23505 on THIS constraint is the race-safe signal
- *  that a concurrent turn already owns the chat — distinct from any other unique
- *  collision, which must NOT be silently treated as "already active". */
-export const ONE_ACTIVE_RUN_PER_CHAT_INDEX = 'ai_chat_runs_one_active_per_chat';
-
-/**
- * Thrown by {@link AiChatRunService.beginRun} when the run-row INSERT loses the
- * race for a chat's single active slot (the partial unique index rejects it with
- * a 23505). This is the AUTHORITATIVE concurrency gate: the controller's cheap
- * pre-check is only a fast-path, and a request that slips past it must NOT run
- * untracked. The caller (AiChatService.stream) translates this into a 409 and
- * aborts the turn BEFORE any AI/provider call.
- */
-export class RunAlreadyActiveError extends Error {
-  constructor(public readonly chatId: string) {
-    super(`An agent run is already in progress for chat ${chatId}`);
-    this.name = 'RunAlreadyActiveError';
-  }
-}
-
-/**
- * The terminal status of a TURN (the #183 assistant-row lifecycle) maps onto the
- * terminal status of a RUN (#184). A turn that completed -> the run succeeded; a
- * turn that errored -> the run failed; a turn aborted (explicit user stop) -> the
- * run aborted. Pure + unit-testable.
- */
-export type TurnTerminalStatus = 'completed' | 'error' | 'aborted';
-export type RunTerminalStatus = 'succeeded' | 'failed' | 'aborted';
-
-export function mapTurnStatusToRun(
-  status: TurnTerminalStatus,
-): RunTerminalStatus {
-  switch (status) {
-    case 'completed':
-      return 'succeeded';
-    case 'error':
-      return 'failed';
-    case 'aborted':
-      return 'aborted';
-  }
-}
-
-/** An in-flight run held in process memory: its AbortController is the ONLY thing
- *  that can stop the turn (an explicit user stop), independent of the browser
- *  socket. A mere disconnect never touches it, so the run keeps going. */
-interface ActiveRun {
-  controller: AbortController;
-  chatId: string;
-  workspaceId: string;
-}
-
-/** The live handle the streaming path drives a run through (returned by
- *  {@link AiChatRunService.beginRun}). The `signal` governs the agent loop's
- *  abort — wired to the run, NOT to the HTTP socket. */
-export interface RunHandle {
-  runId: string;
-  signal: AbortSignal;
-}
-
-/**
- * AiChatRunService (#184 phase 1) — owns the agent RUN as a first-class,
- * server-side lifecycle object detached from the HTTP request / browser window.
- *
- * Responsibilities:
- *  - create a run row when a turn starts (inserted directly as 'running'; the
- *    'pending' status is only the column default + a reserved value, never
- *    written by code in phase 1) and register an in-memory AbortController for it
- *    (the explicit-stop lever);
- *  - finalize the run row (succeeded / failed / aborted) and unregister it;
- *  - service an EXPLICIT user stop (`requestStop`) — the ONLY thing that aborts a
- *    run; a browser disconnect deliberately does NOT;
- *  - crash-recovery sweep of dangling runs on startup.
- *
- * The agent loop itself still runs in AiChatService.stream (reusing #183's
- * step-granular durable write path, `consumeStream` already drains it independent
- * of the socket); this service only wraps it in a durable lifecycle and an
- * abort handle that outlives the subscriber.
- */
-@Injectable()
-export class AiChatRunService implements OnModuleInit {
-  private readonly logger = new Logger(AiChatRunService.name);
-
-  // runId -> ActiveRun. Process-local on purpose (phase 1 is single-process /
-  // in-memory transport; a cross-process BullMQ runner + Redis stop-signal is
-  // deferred to phase 2). A stop for a runId not in this map (e.g. after a
-  // restart) still records `stop_requested_at` on the row.
-  private readonly active = new Map<string, ActiveRun>();
-
-  // runIds whose TERMINAL row write has SUCCEEDED — the idempotency once-gate
-  // (F6). A finalize must short-circuit only AFTER the terminal write has landed,
-  // NOT merely after the in-memory entry was dropped: a transient UPDATE failure
-  // has to stay retryable, so "already settled" means "row already terminal", not
-  // "entry already gone". Grows by one short UUID per finished run over process
-  // uptime — negligible in phase 1's single process.
-  private readonly settled = new Set<string>();
-
-  // Bounded retry for the terminal write (F6): a single PK UPDATE can fail
-  // transiently under many fire-and-forget writes (pool exhaustion, deadlock, a
-  // brief connection blip). Riding out that blip in-place matters because the
-  // dominant success path (streamText onFinish) settles exactly ONCE — if that
-  // write is dropped and never retried, the row is stranded 'running' and the
-  // one-active-run gate 409s every future turn in the chat until a restart (no
-  // periodic sweep in phase 1).
-  private static readonly FINALIZE_MAX_ATTEMPTS = 3;
-  private static readonly FINALIZE_RETRY_BASE_MS = 50;
-
-  constructor(
-    private readonly runRepo: AiChatRunRepo,
-    private readonly environment: EnvironmentService,
-  ) {}
-
-  /**
-   * Crash-recovery sweep on server start: settle EVERY run still left
-   * pending/running to 'aborted' (F1 / DECISION C). The boot sweep is
-   * UNCONDITIONAL — no staleness window — because phase 1 is single-process: on a
-   * fresh boot any pending|running run is definitionally hung (no live runner owns
-   * it), so even a fast restart (deploy/OOM within minutes of the last step) can
-   * no longer leave a run stuck 'running' forever (which would make the
-   * one-active-run gate 409 every future turn in that chat). The staleness window
-   * is reintroduced only for the phase-2 multi-instance timer sweep, where a
-   * booting replica must not abort a run another replica is actively executing.
-   * Best-effort — a sweep failure is logged but MUST NOT block startup (mirrors
-   * AiChatService.onModuleInit for #183).
-   */
-  async onModuleInit(): Promise<void> {
-    this.warnIfMultiInstance();
-    try {
-      // No `staleMs`: unconditional boot sweep (F1). See AiChatRunRepo.sweepRunning.
-      const swept = await this.runRepo.sweepRunning();
-      if (swept > 0) {
-        this.logger.log(
-          `Startup sweep: marked ${swept} dangling agent run(s) as 'aborted'.`,
-        );
-      }
-    } catch (err) {
-      this.logger.warn(
-        `Startup sweep of dangling runs failed: ${
-          err instanceof Error ? err.message : 'unknown error'
-        }`,
-      );
-    }
-  }
-
-  /**
-   * F2 (DECISION A): autonomous runs are SINGLE-INSTANCE-ONLY in phase 1. An
-   * explicit Stop, and the in-memory AbortController that backs it, are
-   * process-local: a Stop only aborts the live turn if it lands on the SAME
-   * replica that owns the run (it still stamps `stop_requested_at` cross-instance,
-   * but nothing reads that flag during an active run yet). Cross-instance pub/sub
-   * stop is phase 2. So if the deployment is horizontally scaled, warn loudly at
-   * startup that a Stop may not reach a run executing on another replica.
-   *
-   * DETECTION: this codebase always wires the socket.io Redis adapter (REDIS_URL
-   * is mandatory), so the adapter alone is NOT a horizontal-scaling signal. The
-   * authoritative signal the codebase has is `CLOUD=true` (EnvironmentService
-   * .isCloud()), the Docmost-cloud multi-replica deployment. We warn whenever that
-   * is set, because any workspace could enable settings.ai.autonomousRuns. A
-   * self-hosted operator running multiple replicas behind a load balancer is also
-   * multi-instance; the deploy docs (.env.example / AGENTS.md) spell out the
-   * single-instance constraint for that case.
-   */
-  private warnIfMultiInstance(): void {
-    if (this.environment.isCloud()) {
-      this.logger.warn(
-        'Autonomous agent runs (settings.ai.autonomousRuns) are SINGLE-INSTANCE-ONLY ' +
-          'in phase 1: a horizontally-scaled deployment was detected (CLOUD=true). ' +
-          'An explicit Stop only aborts a run executing on the same replica that owns ' +
-          'it (cross-instance Stop is not yet reliable — phase 2). Run a single ' +
-          'instance if you enable autonomousRuns, or keep the flag off.',
-      );
-    }
-  }
-
-  /**
-   * Start a run for a turn: insert the run row (status 'running', startedAt now),
-   * register a fresh AbortController for it, and return a {@link RunHandle} whose
-   * `signal` the agent loop uses. The DB partial unique index guarantees at most
-   * one active run per chat — a second concurrent start on the same chat REJECTS
-   * at the insert (a 23505 on {@link ONE_ACTIVE_RUN_PER_CHAT_INDEX}). That
-   * rejection is the AUTHORITATIVE race gate: it is surfaced as a distinct
-   * {@link RunAlreadyActiveError} (NOT swallowed), so the caller turns it into a
-   * 409 and never streams an untracked turn. The controller is registered AFTER a
-   * successful insert so a rejected start leaks nothing.
-   */
-  async beginRun(args: {
-    chatId: string;
-    workspaceId: string;
-    userId: string;
-    trigger?: string;
-  }): Promise<RunHandle> {
-    let run: AiChatRun;
-    try {
-      run = await this.runRepo.insert({
-        chatId: args.chatId,
-        workspaceId: args.workspaceId,
-        createdBy: args.userId,
-        trigger: args.trigger ?? 'user',
-        status: 'running',
-        startedAt: new Date(),
-      });
-    } catch (err) {
-      // The race backstop: a concurrent turn already holds this chat's single
-      // active slot, so the partial unique index rejected our insert. Surface a
-      // distinct signal — the caller MUST reject this turn (409), not run it
-      // untracked. Any OTHER error propagates unchanged.
-      if (
-        isUniqueViolation(err) &&
-        violatedConstraint(err) === ONE_ACTIVE_RUN_PER_CHAT_INDEX
-      ) {
-        throw new RunAlreadyActiveError(args.chatId);
-      }
-      throw err;
-    }
-    const controller = new AbortController();
-    this.active.set(run.id, {
-      controller,
-      chatId: args.chatId,
-      workspaceId: args.workspaceId,
-    });
-    return { runId: run.id, signal: controller.signal };
-  }
-
-  /** Link the assistant message (the #183 projection) to its run. Best-effort. */
-  async linkAssistantMessage(
-    runId: string,
-    workspaceId: string,
-    assistantMessageId: string,
-  ): Promise<void> {
-    try {
-      await this.runRepo.update(runId, workspaceId, { assistantMessageId });
-    } catch (err) {
-      this.logger.warn(
-        `Failed to link assistant message to run ${runId}: ${
-          err instanceof Error ? err.message : 'unknown error'
-        }`,
-      );
-    }
-  }
-
-  /** Persist progress: bump the run's finished-step count. Best-effort (never
-   *  blocks or breaks the stream). */
-  async recordStep(
-    runId: string,
-    workspaceId: string,
-    stepCount: number,
-  ): Promise<void> {
-    try {
-      await this.runRepo.update(runId, workspaceId, { stepCount });
-    } catch (err) {
-      this.logger.warn(
-        `Failed to record step for run ${runId}: ${
-          err instanceof Error ? err.message : 'unknown error'
-        }`,
-      );
-    }
-  }
-
-  /**
-   * Finalize a run to its terminal status (succeeded / failed / aborted),
-   * stamping finishedAt + any error. Best-effort, but ROBUST against a transient
-   * terminal-write failure (F6) AND atomically safe against a concurrent settle.
-   *
-   * ATOMIC ONCE-CLAIM (the gate must close in ONE synchronous tick): two
-   * finalizeRun calls for the SAME run can race — the documented real path is
-   * AiChatService.stream's safety-net catch settling the turn to 'error' while a
-   * streamText terminal callback (onFinish/onAbort/onError) ALSO settles it. The
-   * `settled.has` check alone is NOT a gate: it is read BEFORE the awaited UPDATE,
-   * so two callers can both see `false` and both write the row (last-write-wins
-   * clobbers the real terminal status, and the bounded retry only widens that
-   * window). The claim therefore happens via `active.delete`, a SYNCHRONOUS
-   * check-and-clear with NO await between the gate and the entry removal: the
-   * second concurrent caller finds the entry already gone and returns in the same
-   * tick, before any UPDATE. The transition "nobody is finalizing" -> "I am
-   * finalizing" is thus a single atomic step.
-   *
-   * ORDER MATTERS (F6): once we own the claim, the terminal UPDATE happens FIRST;
-   * only once it SUCCEEDS do we record the run as settled. If the UPDATE fails on
-   * every bounded attempt we RESTORE the in-memory entry, leave the run UNsettled,
-   * and emit an ERROR signal that the row is left non-terminal 'running' (which
-   * would 409 every future turn in the chat until recovery). An in-process retry
-   * by a LATER settle is only POSSIBLE, never guaranteed: it needs (a) the entry
-   * to have been restored at the give-up path AND (b) a fresh settler to arrive
-   * AFTER that restore. A concurrent settler that arrives DURING the retry window
-   * — while the entry is deleted for backoff and not yet restored — is consumed at
-   * the synchronous `active.delete` claim (it finds nothing to delete and returns
-   * a no-op), so it does NOT become an in-process retrier. The NO-streamText path
-   * (the turn threw before streamText was wired, so ONLY the safety-net ever
-   * settles) likewise has no second in-process settler at all. The UNCONDITIONAL
-   * backstop in every case is the boot sweep on the next restart (phase 1 has no
-   * periodic in-process sweep); the retained entry is bounded (cleared on restart)
-   * and harmless meanwhile.
-   *
-   * IDEMPOTENT on SUCCESS (#184 review): the terminal write happens AT MOST ONCE
-   * per run. After a successful write the once-gate keys off {@link settled} (the
-   * terminal row already written) so a settle arriving AFTER the entry was already
-   * dropped-and-settled returns early; a settle racing the in-flight write is
-   * stopped earlier still, by the `active.delete` claim. Either way a genuine
-   * double-settle collapses to a single write and a late settle can never clobber
-   * the real terminal status or double-write the row.
-   */
-  async finalizeRun(
-    runId: string,
-    workspaceId: string,
-    turnStatus: TurnTerminalStatus,
-    error?: string,
-  ): Promise<void> {
-    // ---- Atomic once-claim (synchronous; NO await before the gate closes) ----
-    // Already terminally written -> idempotent no-op.
-    if (this.settled.has(runId)) return;
-    // Capture the entry BEFORE the delete so a total-failure path can restore it.
-    const entry = this.active.get(runId);
-    // SYNCHRONOUS check-and-clear: the FIRST caller deletes (claims) the entry;
-    // any concurrent SECOND caller finds nothing to delete and returns HERE, in
-    // the same tick, before any await — so it can never reach the UPDATE.
-    if (!this.active.delete(runId)) return;
-
-    let lastError: unknown;
-    for (
-      let attempt = 1;
-      attempt <= AiChatRunService.FINALIZE_MAX_ATTEMPTS;
-      attempt++
-    ) {
-      try {
-        await this.runRepo.update(runId, workspaceId, {
-          status: mapTurnStatusToRun(turnStatus),
-          finishedAt: new Date(),
-          error: error ?? null,
-        });
-        // Terminal write landed: arm the once-gate. The entry is already gone
-        // (claimed above); we do NOT restore it. The slot is now free.
-        this.settled.add(runId);
-        return;
-      } catch (err) {
-        lastError = err;
-        this.logger.warn(
-          `Failed to finalize run ${runId} (attempt ${attempt}/${
-            AiChatRunService.FINALIZE_MAX_ATTEMPTS
-          }): ${err instanceof Error ? err.message : 'unknown error'}`,
-        );
-        if (attempt < AiChatRunService.FINALIZE_MAX_ATTEMPTS) {
-          await this.delay(AiChatRunService.FINALIZE_RETRY_BASE_MS * attempt);
-        }
-      }
-    }
-    // Every attempt failed: this is a give-up, materially worse than a per-attempt
-    // blip — the row is left NON-TERMINAL ('running'), so emit ONE explicit,
-    // greppable ERROR so an operator can tell "survived a blip" from "gave up, run
-    // held in memory until recovery" (the last warn alone says only "attempt 3/3").
-    this.logger.error(
-      `Run ${runId} (chat ${entry?.chatId ?? 'unknown'}) left NON-TERMINAL ` +
-        `('running'): terminal write failed after ${
-          AiChatRunService.FINALIZE_MAX_ATTEMPTS
-        } attempts; entry retained in memory, recovery deferred to next settle / ` +
-        `boot sweep`,
-      lastError,
-    );
-    // RESTORE the claimed entry (and leave the run UNsettled) so a LATER settle
-    // that arrives AFTER this restore MAY retry the terminal write — but that
-    // in-process retry is NOT guaranteed (a concurrent settler caught in the retry
-    // window above is consumed at the `active.delete` claim, and the no-streamText
-    // path has no second settler at all). The UNCONDITIONAL backstop in every case
-    // is the boot sweep on the next restart; the restored entry is bounded and
-    // cleared on restart.
-    if (entry) this.active.set(runId, entry);
-  }
-
-  /** Small async backoff between terminal-write retries (F6). Isolated so it is
-   *  trivial to stub/fake-time in tests. */
-  private delay(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-
-  /**
-   * Request an EXPLICIT stop of a run (the user pressed Stop). This is the ONLY
-   * thing that aborts a run — distinct from a browser disconnect, which leaves
-   * the run going. Aborts the in-process controller FIRST (the only thing that
-   * actually stops the run, if this replica owns it), then makes a best-effort
-   * attempt to stamp `stop_requested_at` — that audit write stamps only while the
-   * row is active and may be skipped on a DB error or lost to the finalize race,
-   * which is acceptable since the row still settles as 'aborted'. Returns true
-   * when a stop took effect (row marked and/or controller aborted), false when
-   * there was nothing active to stop.
-   */
-  async requestStop(runId: string, workspaceId: string): Promise<boolean> {
-    const entry = this.active.get(runId);
-    if (entry) {
-      // Abort the live turn FIRST -> streamText onAbort fires -> the partial is
-      // persisted (#183) and finalizeRun settles the row as 'aborted'. This is
-      // the ONLY thing that aborts a run, so it MUST NOT be hostage to the audit
-      // write below: a transient failure on `markStopRequested` (pool exhaustion,
-      // deadlock, dropped connection) must never leave the run executing despite
-      // an explicit Stop. At worst only the `stop_requested_at` timestamp is lost.
-      entry.controller.abort();
-    }
-    // Record `stop_requested_at` (best-effort). A transient DB failure here is
-    // logged and treated as `marked = false`; the abort above already took
-    // effect, so we never rethrow and skip stopping the run. Note: because
-    // markStopRequested only stamps while the row is active, aborting first means
-    // even a healthy write can lose the race against the resulting finalize and
-    // skip the stamp — acceptable, as the row still settles as 'aborted' and only
-    // this audit timestamp may be lost.
-    let marked: unknown;
-    try {
-      marked = await this.runRepo.markStopRequested(runId, workspaceId);
-    } catch (err) {
-      marked = undefined;
-      this.logger.warn(
-        `requestStop: markStopRequested failed for run ${runId} ` +
-          `(stop_requested_at not recorded); abort already issued: ` +
-          `${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-    return Boolean(marked) || Boolean(entry);
-  }
-
-  /** Latest persisted run for a chat — the reconnect target (an in-flight or
-   *  finished run). Pure read-through to the repo. */
-  getLatestForChat(
-    chatId: string,
-    workspaceId: string,
-  ): Promise<AiChatRun | undefined> {
-    return this.runRepo.findLatestByChat(chatId, workspaceId);
-  }
-
-  /** Fetch a run by id (workspace-scoped). Used to resolve + ownership-check an
-   *  explicit stop targeting a runId. */
-  getRun(runId: string, workspaceId: string): Promise<AiChatRun | undefined> {
-    return this.runRepo.findById(runId, workspaceId);
-  }
-
-  /** The active run on a chat, if any (used to reject a concurrent start with a
-   *  clean 409 before committing to the stream). */
-  getActiveForChat(
-    chatId: string,
-    workspaceId: string,
-  ): Promise<AiChatRun | undefined> {
-    return this.runRepo.findActiveByChat(chatId, workspaceId);
-  }
-
-  /** Test/diagnostic seam: whether this replica is holding a live controller for
-   *  the run. */
-  isLocallyActive(runId: string): boolean {
-    return this.active.has(runId);
-  }
-}

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

@@ -19,7 +19,6 @@ describe('AiChatController.boundChat', () => {
     };
     const controller = new AiChatController(
       {} as never,
-      {} as never, // aiChatRunService
       aiChatRepo as never,
       {} as never,
       {} as never,

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

@@ -53,7 +53,6 @@ describe('AiChatController.export', () => {
     };
     const controller = new AiChatController(
       {} as never,
-      {} as never, // aiChatRunService
       aiChatRepo as never,
       aiChatMessageRepo as never,
       {} as never,

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

@@ -1,163 +0,0 @@
-import { BadRequestException, ForbiddenException } from '@nestjs/common';
-import { AiChatController } from './ai-chat.controller';
-import type { User, Workspace } from '@docmost/db/types/entity.types';
-
-/**
- * Wiring spec for the #184 run-reconnect / run-stop endpoints
- * (`POST /ai-chat/run` and `POST /ai-chat/stop`). Both are OWNER-gated via
- * assertOwnedChat (the requesting user must own the chat) and NOT flag-gated.
- * Exercised with hand-rolled mocks — no Nest graph, no DB. The controller's
- * constructor order is (aiChatService, aiChatRunService, aiChatRepo,
- * aiChatMessageRepo, aiTranscription).
- */
-describe('AiChatController run endpoints (#184)', () => {
-  const user = { id: 'u1' } as User;
-  const workspace = { id: 'ws1' } as Workspace;
-
-  function makeController(opts: {
-    chat?: unknown; // what aiChatRepo.findById returns (owner-gate)
-    run?: unknown; // getLatestForChat / getRun result
-    activeRun?: unknown; // getActiveForChat result
-    message?: unknown; // aiChatMessageRepo.findById result
-    stopped?: boolean; // requestStop result
-  }) {
-    const aiChatRunService = {
-      getLatestForChat: jest.fn().mockResolvedValue(opts.run),
-      getRun: jest.fn().mockResolvedValue(opts.run),
-      getActiveForChat: jest.fn().mockResolvedValue(opts.activeRun),
-      requestStop: jest.fn().mockResolvedValue(opts.stopped ?? false),
-    };
-    const aiChatRepo = {
-      findById: jest.fn().mockResolvedValue(opts.chat),
-    };
-    const aiChatMessageRepo = {
-      findById: jest.fn().mockResolvedValue(opts.message),
-    };
-    const controller = new AiChatController(
-      {} as never, // aiChatService
-      aiChatRunService as never,
-      aiChatRepo as never,
-      aiChatMessageRepo as never,
-      {} as never, // aiTranscription
-    );
-    return { controller, aiChatRunService, aiChatRepo, aiChatMessageRepo };
-  }
-
-  describe('POST /ai-chat/run (getRun)', () => {
-    it('owner-gates: a chat the user does not own throws ForbiddenException', async () => {
-      const { controller, aiChatRunService } = makeController({
-        chat: { id: 'c1', creatorId: 'someone-else' },
-      });
-      await expect(
-        controller.getRun({ chatId: 'c1' }, user, workspace),
-      ).rejects.toBeInstanceOf(ForbiddenException);
-      // It must NOT reach the run lookup once the owner-gate fails.
-      expect(aiChatRunService.getLatestForChat).not.toHaveBeenCalled();
-    });
-
-    it('returns { run: null, message: null } when the chat has never had a run', async () => {
-      const { controller, aiChatRunService } = makeController({
-        chat: { id: 'c1', creatorId: 'u1' },
-        run: undefined,
-      });
-      const res = await controller.getRun({ chatId: 'c1' }, user, workspace);
-      expect(res).toEqual({ run: null, message: null });
-      expect(aiChatRunService.getLatestForChat).toHaveBeenCalledWith(
-        'c1',
-        'ws1',
-      );
-    });
-
-    it('returns the run and its projected assistant message', async () => {
-      const run = { id: 'run-1', chatId: 'c1', assistantMessageId: 'm1' };
-      const message = { id: 'm1', role: 'assistant' };
-      const { controller, aiChatMessageRepo } = makeController({
-        chat: { id: 'c1', creatorId: 'u1' },
-        run,
-        message,
-      });
-      const res = await controller.getRun({ chatId: 'c1' }, user, workspace);
-      expect(res).toEqual({ run, message });
-      expect(aiChatMessageRepo.findById).toHaveBeenCalledWith('m1', 'ws1');
-    });
-
-    it('returns message: null when the run has no linked assistant message', async () => {
-      const run = { id: 'run-1', chatId: 'c1', assistantMessageId: null };
-      const { controller, aiChatMessageRepo } = makeController({
-        chat: { id: 'c1', creatorId: 'u1' },
-        run,
-      });
-      const res = await controller.getRun({ chatId: 'c1' }, user, workspace);
-      expect(res).toEqual({ run, message: null });
-      expect(aiChatMessageRepo.findById).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('POST /ai-chat/stop (stopRun)', () => {
-    it('throws BadRequestException when neither runId nor chatId is given', async () => {
-      const { controller } = makeController({});
-      await expect(
-        controller.stopRun({}, user, workspace),
-      ).rejects.toBeInstanceOf(BadRequestException);
-    });
-
-    it('stops by runId: owner-gates via the run’s chat, then requests the stop', async () => {
-      const { controller, aiChatRunService, aiChatRepo } = makeController({
-        run: { id: 'run-1', chatId: 'c1' },
-        chat: { id: 'c1', creatorId: 'u1' },
-        stopped: true,
-      });
-      const res = await controller.stopRun({ runId: 'run-1' }, user, workspace);
-      expect(res).toEqual({ stopped: true });
-      expect(aiChatRunService.getRun).toHaveBeenCalledWith('run-1', 'ws1');
-      expect(aiChatRepo.findById).toHaveBeenCalledWith('c1', 'ws1');
-      expect(aiChatRunService.requestStop).toHaveBeenCalledWith('run-1', 'ws1');
-    });
-
-    it('stops by runId: a foreign run’s chat throws ForbiddenException (no stop)', async () => {
-      const { controller, aiChatRunService } = makeController({
-        run: { id: 'run-1', chatId: 'c1' },
-        chat: { id: 'c1', creatorId: 'someone-else' },
-      });
-      await expect(
-        controller.stopRun({ runId: 'run-1' }, user, workspace),
-      ).rejects.toBeInstanceOf(ForbiddenException);
-      expect(aiChatRunService.requestStop).not.toHaveBeenCalled();
-    });
-
-    it('stops by runId: an unknown run reports { stopped: false }', async () => {
-      const { controller, aiChatRunService } = makeController({
-        run: undefined,
-      });
-      const res = await controller.stopRun({ runId: 'gone' }, user, workspace);
-      expect(res).toEqual({ stopped: false });
-      expect(aiChatRunService.requestStop).not.toHaveBeenCalled();
-    });
-
-    it('stops by chatId: owner-gates, resolves the active run, requests the stop', async () => {
-      const { controller, aiChatRunService, aiChatRepo } = makeController({
-        chat: { id: 'c1', creatorId: 'u1' },
-        activeRun: { id: 'run-9' },
-        stopped: true,
-      });
-      const res = await controller.stopRun({ chatId: 'c1' }, user, workspace);
-      expect(res).toEqual({ stopped: true });
-      expect(aiChatRepo.findById).toHaveBeenCalledWith('c1', 'ws1');
-      expect(aiChatRunService.getActiveForChat).toHaveBeenCalledWith(
-        'c1',
-        'ws1',
-      );
-      expect(aiChatRunService.requestStop).toHaveBeenCalledWith('run-9', 'ws1');
-    });
-
-    it('stops by chatId: reports { stopped: false } when no run is active', async () => {
-      const { controller, aiChatRunService } = makeController({
-        chat: { id: 'c1', creatorId: 'u1' },
-        activeRun: undefined,
-      });
-      const res = await controller.stopRun({ chatId: 'c1' }, user, workspace);
-      expect(res).toEqual({ stopped: false });
-      expect(aiChatRunService.requestStop).not.toHaveBeenCalled();
-    });
-  });
-});

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

@@ -1,7 +1,6 @@
 import {
   BadRequestException,
   Body,
-  ConflictException,
   Controller,
   ForbiddenException,
   HttpCode,
@@ -21,25 +20,14 @@ import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
 import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
 import { SkipTransform } from '../../common/decorators/skip-transform.decorator';
-import {
-  AiChat,
-  AiChatMessage,
-  AiChatRun,
-  User,
-  Workspace,
-} from '@docmost/db/types/entity.types';
+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 { UserThrottlerGuard } from '../../integrations/throttle/user-throttler.guard';
 import { AI_CHAT_THROTTLER } from '../../integrations/throttle/throttler-names';
 import { FileInterceptor } from '../../common/interceptors/file.interceptor';
-import {
-  AiChatRunHooks,
-  AiChatService,
-  AiChatStreamBody,
-} from './ai-chat.service';
-import { AiChatRunService } from './ai-chat-run.service';
+import { AiChatService, AiChatStreamBody } from './ai-chat.service';
 import { AiTranscriptionService } from './ai-transcription.service';
 import {
   BoundChatDto,
@@ -47,9 +35,7 @@ import {
   ExportChatDto,
   GeneratePageTitleDto,
   GetChatMessagesDto,
-  GetRunDto,
   RenameChatDto,
-  StopRunDto,
 } from './dto/ai-chat.dto';
 import { describeProviderError } from '../../integrations/ai/ai-error.util';
 import { buildChatMarkdown } from './chat-markdown.util';
@@ -66,7 +52,6 @@ export class AiChatController {
 
   constructor(
     private readonly aiChatService: AiChatService,
-    private readonly aiChatRunService: AiChatRunService,
     private readonly aiChatRepo: AiChatRepo,
     private readonly aiChatMessageRepo: AiChatMessageRepo,
     private readonly aiTranscription: AiTranscriptionService,
@@ -152,75 +137,6 @@ export class AiChatController {
     return { markdown };
   }
 
-  /**
-   * Reconnect to the latest run of a chat (#184 phase 1). Returns the run's
-   * persisted lifecycle state ({ status, error, stepCount, timings, ... }) plus
-   * the assistant message it projects (the partial/final output) — the DB is the
-   * source of truth, so this works for an in-flight run (the browser dropped, the
-   * run kept going) and a finished one alike. Owner-gated via assertOwnedChat.
-   * `{ run: null }` when the chat has never had a run.
-   */
-  @HttpCode(HttpStatus.OK)
-  @Post('run')
-  async getRun(
-    @Body() dto: GetRunDto,
-    @AuthUser() user: User,
-    @AuthWorkspace() workspace: Workspace,
-  ): Promise<{ run: AiChatRun | null; message: AiChatMessage | null }> {
-    await this.assertOwnedChat(dto.chatId, user, workspace);
-    const run = await this.aiChatRunService.getLatestForChat(
-      dto.chatId,
-      workspace.id,
-    );
-    if (!run) return { run: null, message: null };
-    const message = run.assistantMessageId
-      ? await this.aiChatMessageRepo.findById(
-          run.assistantMessageId,
-          workspace.id,
-        )
-      : undefined;
-    return { run, message: message ?? null };
-  }
-
-  /**
-   * Explicitly STOP an agent run (#184 phase 1) — the user pressed Stop. This is
-   * the ONLY thing that ends a detached run; a browser disconnect deliberately
-   * does not. Target by `runId` (from the streamed start metadata) or by `chatId`
-   * (stop whatever run is active on it). Owner-gated. Returns
-   * `{ stopped }` — false when there was nothing active to stop.
-   */
-  @HttpCode(HttpStatus.OK)
-  @Post('stop')
-  async stopRun(
-    @Body() dto: StopRunDto,
-    @AuthUser() user: User,
-    @AuthWorkspace() workspace: Workspace,
-  ): Promise<{ stopped: boolean }> {
-    let runId = dto.runId;
-    if (!runId && !dto.chatId) {
-      throw new BadRequestException('runId or chatId is required');
-    }
-    if (runId) {
-      // Resolve the run to its chat and owner-gate via that chat.
-      const run = await this.aiChatRunService.getRun(runId, workspace.id);
-      if (!run) return { stopped: false };
-      await this.assertOwnedChat(run.chatId, user, workspace);
-    } else {
-      await this.assertOwnedChat(dto.chatId!, user, workspace);
-      const active = await this.aiChatRunService.getActiveForChat(
-        dto.chatId!,
-        workspace.id,
-      );
-      if (!active) return { stopped: false };
-      runId = active.id;
-    }
-    const stopped = await this.aiChatRunService.requestStop(
-      runId,
-      workspace.id,
-    );
-    return { stopped };
-  }
-
   /** Rename a chat. */
   @HttpCode(HttpStatus.OK)
   @Post('rename')
@@ -272,20 +188,11 @@ export class AiChatController {
     @AuthWorkspace() workspace: Workspace,
   ): Promise<void> {
     // A7 gate: the workspace must have AI chat explicitly enabled.
-    const settings = (workspace.settings ?? {}) as {
-      ai?: { chat?: boolean; autonomousRuns?: boolean };
-    };
+    const settings = (workspace.settings ?? {}) as { ai?: { chat?: boolean } };
     if (settings.ai?.chat !== true) {
       throw new ForbiddenException('AI chat is disabled');
     }
 
-    // #184 phase 1 flag: when ON, the turn becomes a detached, durable RUN — its
-    // lifecycle is tracked in ai_chat_runs, a browser disconnect no longer aborts
-    // it, and only an explicit /ai-chat/stop ends it. When OFF (the default) the
-    // turn is socket-bound exactly as before, so existing deployments are
-    // unaffected.
-    const autonomousRuns = settings.ai?.autonomousRuns === true;
-
     const sessionId = (req.raw as { sessionId?: string }).sessionId;
     if (!sessionId) {
       // The chat requires an interactive session to mint loopback tokens
@@ -309,58 +216,6 @@ export class AiChatController {
     // HttpException) instead of breaking mid-stream.
     const model = await this.aiChatService.getChatModel(workspace.id, role);
 
-    // #184: one active run per chat. For an EXISTING chat reject a concurrent
-    // start with a clean 409 BEFORE hijack (the common double-submit / second-tab
-    // case), so the user gets JSON, not a mid-stream error. A brand-new chat
-    // (no chatId) cannot have a prior run, and the DB partial unique index is the
-    // backstop against any race that slips past this check.
-    if (autonomousRuns && body.chatId) {
-      const active = await this.aiChatRunService.getActiveForChat(
-        body.chatId,
-        workspace.id,
-      );
-      if (active) {
-        throw new ConflictException({
-          message: 'An agent run is already in progress for this chat',
-          code: 'A_RUN_ALREADY_ACTIVE',
-        });
-      }
-    }
-
-    // Run-lifecycle hooks (#184), only when the flag is on. They wrap the turn in
-    // a durable run whose abort is governed by the run (explicit stop), persist
-    // its progress, and settle its terminal status — see AiChatRunService.
-    const runHooks: AiChatRunHooks | undefined = autonomousRuns
-      ? {
-          begin: (chatId) =>
-            this.aiChatRunService.beginRun({
-              chatId,
-              workspaceId: workspace.id,
-              userId: user.id,
-              trigger: 'user',
-            }),
-          onAssistantSeeded: (runId, messageId) =>
-            this.aiChatRunService.linkAssistantMessage(
-              runId,
-              workspace.id,
-              messageId,
-            ),
-          onStep: (runId, stepCount) =>
-            void this.aiChatRunService.recordStep(
-              runId,
-              workspace.id,
-              stepCount,
-            ),
-          onSettled: (runId, status, error) =>
-            this.aiChatRunService.finalizeRun(
-              runId,
-              workspace.id,
-              status,
-              error,
-            ),
-        }
-      : undefined;
-
     // Abort the agent loop when the client disconnects. `close` also fires on
     // normal completion, so only abort when the response has not finished
     // writing (a genuine disconnect). `once` fires at most once and self-removes;
@@ -375,44 +230,18 @@ export class AiChatController {
       // A genuine disconnect leaves the response unfinished (unlike a normal
       // completion, which also fires `close`). Such a drop — e.g. a reverse
       // proxy cutting the SSE mid-answer — is otherwise invisible server-side,
-      // so log it here.
+      // so log it here before aborting the agent loop.
       if (!res.raw.writableEnded) {
-        if (autonomousRuns) {
-          // #184: the turn is a DETACHED run. A disconnect must NOT abort it —
-          // the run keeps executing and persisting server-side; the client
-          // reconnects via /ai-chat/run (or re-stops via /ai-chat/stop). Log only.
-          this.logger.log(
-            `AI chat stream: client disconnected; run continues server-side ` +
-              `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
-          );
-        } else {
-          this.logger.warn(
-            `AI chat stream: client disconnected before completion; aborting turn ` +
-              `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
-          );
-          controller.abort();
-        }
+        this.logger.warn(
+          `AI chat stream: client disconnected before completion; aborting turn ` +
+            `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
+        );
+        controller.abort();
       }
     };
     req.raw.once('close', onClose);
     res.raw.once('finish', () => req.raw.off('close', onClose));
 
-    // #184: in detached mode the turn is NOT aborted on disconnect, so the SDK's
-    // pipe keeps writing to a socket the client may have dropped — for the rest of
-    // the (continuing) run. A write to the dead socket can emit an 'error' on the
-    // raw response; without a listener that surfaces as an unhandled error event.
-    // Swallow it (the run continues server-side regardless). Legacy mode aborts on
-    // disconnect, so it does not need this and keeps its exact prior behavior.
-    if (autonomousRuns) {
-      res.raw.on('error', (err) => {
-        this.logger.debug(
-          `AI chat detached stream: post-disconnect socket error swallowed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-      });
-    }
-
     // Commit to streaming: hijack so Fastify stops managing the response and
     // the AI SDK can write the UI-message stream directly to the Node socket.
     res.hijack();
@@ -427,32 +256,15 @@ export class AiChatController {
         signal: controller.signal,
         model,
         role,
-        // #184: present only when the flag is on; wraps the turn in a durable run.
-        runHooks,
       });
     } catch (err) {
-      // Any failure AFTER hijack can no longer go through Nest's exception
-      // filter, so emit the error on the raw socket if nothing has been written
-      // yet. The lost-the-race 409 (RunAlreadyActiveError -> ConflictException)
-      // is raised by stream() BEFORE it writes a byte, so headers are still
-      // unsent here: honor the HttpException's real status + body (a clean 409),
-      // not a blanket 500. Everything else stays a 500.
-      const isHttp = err instanceof HttpException;
-      if (!isHttp) {
-        this.logger.error('AI chat stream failed', err as Error);
-      }
+      // Any failure AFTER hijack can no longer send a clean JSON error, so emit
+      // a minimal error on the raw socket if nothing has been written yet.
+      this.logger.error('AI chat stream failed', err as Error);
       if (!res.raw.headersSent) {
-        const status = isHttp ? err.getStatus() : 500;
-        const payload = isHttp
-          ? err.getResponse()
-          : { error: 'Internal server error' };
-        res.raw.statusCode = status;
+        res.raw.statusCode = 500;
         res.raw.setHeader('Content-Type', 'application/json');
-        res.raw.end(
-          JSON.stringify(
-            typeof payload === 'string' ? { message: payload } : payload,
-          ),
-        );
+        res.raw.end(JSON.stringify({ error: 'Internal server error' }));
       } else if (!res.raw.writableEnded) {
         res.raw.end();
       }

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

@@ -57,7 +57,6 @@ describe('AiChatController.generatePageTitle', () => {
     const aiChatService = { generatePageTitle: generate };
     const controller = new AiChatController(
       aiChatService as never,
-      {} as never, // aiChatRunService
       {} as never,
       {} as never,
       {} as never,

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

@@ -3,7 +3,6 @@ import { AiModule } from '../../integrations/ai/ai.module';
 import { TokenModule } from '../auth/token.module';
 import { AiChatController } from './ai-chat.controller';
 import { AiChatService } from './ai-chat.service';
-import { AiChatRunService } from './ai-chat-run.service';
 import { AiTranscriptionService } from './ai-transcription.service';
 import { AiChatToolsService } from './tools/ai-chat-tools.service';
 import { EmbeddingModule } from './embedding/embedding.module';
@@ -43,7 +42,6 @@ import { PublicShareChatToolsService } from './tools/public-share-chat-tools.ser
   controllers: [AiChatController, PublicShareChatController],
   providers: [
     AiChatService,
-    AiChatRunService,
     AiTranscriptionService,
     AiChatToolsService,
     PublicShareChatService,

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.lifecycle.spec.ts

@@ -1,7 +1,5 @@
 import { Logger } from '@nestjs/common';
-import { AiChatService, AiChatRunHooks } from './ai-chat.service';
-import { AiChatRunService } from './ai-chat-run.service';
-import type { User, Workspace } from '@docmost/db/types/entity.types';
+import { AiChatService } from './ai-chat.service';
 
 /**
  * Lifecycle unit tests for AiChatService.onModuleInit (#183 crash-recovery
@@ -62,98 +60,3 @@ describe('AiChatService.onModuleInit (startup sweep)', () => {
     expect(String(warnSpy.mock.calls[0][0])).toContain('db unavailable');
   });
 });
-
-/**
- * #184 CRITICAL run-lifecycle safety net (review fix). A transient failure
- * AFTER a successful beginRun but BEFORE streamText's terminal callbacks own the
- * lifecycle must STILL settle the run — otherwise the run row is stuck 'running'
- * forever (sweepRunning only runs at startup) and the partial unique index + the
- * controller pre-check 409 every future turn in that chat until a restart. Here
- * we model the very first bare await after beginRun (the user-message insert)
- * throwing, wiring the run hooks to a REAL AiChatRunService (mock repo) exactly
- * as the controller does, and assert the run is settled to 'error' and its
- * in-memory entry dropped (so a follow-up turn would NOT be 409'd).
- */
-describe('AiChatService.stream run-lifecycle safety net (#184)', () => {
-  const user = { id: 'u1' } as User;
-  const workspace = { id: 'ws1' } as Workspace;
-
-  afterEach(() => jest.restoreAllMocks());
-
-  it('an exception after beginRun settles the run to error and drops the in-memory entry', async () => {
-    jest.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
-
-    // Real run service over a mock repo, so finalizeRun's in-memory bookkeeping
-    // (active.delete) is exercised for real.
-    const runRepo = {
-      insert: jest.fn().mockResolvedValue({ id: 'run-1', status: 'running' }),
-      update: jest.fn().mockResolvedValue({ id: 'run-1' }),
-    };
-    const runService = new AiChatRunService(runRepo as never, { isCloud: () => false } as never);
-
-    // The user-message insert (the first bare await after beginRun) throws.
-    const aiChatMessageRepo = {
-      insert: jest.fn().mockRejectedValue(new Error('insert boom')),
-    };
-    const aiChatRepo = {
-      // Existing chat -> chatId stays, no new-chat insert path.
-      findById: jest.fn().mockResolvedValue({ id: 'chat-1', creatorId: 'u1' }),
-    };
-
-    const service = new AiChatService(
-      {} as never, // ai
-      aiChatRepo as never,
-      aiChatMessageRepo as never,
-      {} as never, // aiChatPageSnapshotRepo
-      {} as never, // aiSettings
-      {} as never, // tools
-      {} as never, // mcpClients
-      {} as never, // aiAgentRoleRepo
-      {} as never, // pageRepo
-      {} as never, // pageAccess
-    );
-
-    const runHooks: AiChatRunHooks = {
-      begin: (chatId) =>
-        runService.beginRun({
-          chatId,
-          workspaceId: workspace.id,
-          userId: user.id,
-          trigger: 'user',
-        }),
-      onSettled: (runId, status, error) =>
-        runService.finalizeRun(runId, workspace.id, status, error),
-    };
-
-    await expect(
-      service.stream({
-        user,
-        workspace,
-        sessionId: 'sess',
-        body: {
-          chatId: 'chat-1',
-          messages: [
-            { id: 'm', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
-          ],
-        },
-        res: {} as never,
-        signal: new AbortController().signal,
-        model: {} as never,
-        role: null,
-        runHooks,
-      }),
-    ).rejects.toThrow('insert boom');
-
-    // The run was begun...
-    expect(runRepo.insert).toHaveBeenCalledTimes(1);
-    // ...then settled to a terminal FAILED status by the safety net...
-    expect(runRepo.update).toHaveBeenCalledTimes(1);
-    expect(runRepo.update).toHaveBeenCalledWith(
-      'run-1',
-      'ws1',
-      expect.objectContaining({ status: 'failed' }),
-    );
-    // ...and the in-memory entry is gone, so a follow-up turn is NOT 409'd.
-    expect(runService.isLocallyActive('run-1')).toBe(false);
-  });
-});

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

@@ -1,486 +0,0 @@
-import { ConflictException, Logger } from '@nestjs/common';
-
-// Mock the AI SDK so we can PROVE no provider call is made for the turn we are
-// about to reject. The race rejection happens at runHooks.begin(), long before
-// any streamText/generateText, so these never resolve a real model.
-jest.mock('ai', () => ({
-  streamText: jest.fn(),
-  generateText: jest.fn(),
-  convertToModelMessages: jest.fn(() => []),
-  stepCountIs: jest.fn(() => () => false),
-}));
-
-import { streamText, generateText } from 'ai';
-import { AiChatService } from './ai-chat.service';
-import { RunAlreadyActiveError } from './ai-chat-run.service';
-
-/**
- * Race-closure coverage for the "one active run per chat" guard (#184).
- *
- * THE BUG: two simultaneous POST /ai-chat/stream on the same chat both pass the
- * controller's cheap pre-check (TOCTOU), so the loser's run-row INSERT hits the
- * partial unique index. Previously that 23505 was SWALLOWED and the second turn
- * streamed UNTRACKED (no runId, not stoppable). THE FIX: beginRun surfaces a
- * RunAlreadyActiveError and stream() turns it into a 409 BEFORE any AI call —
- * the second turn never runs.
- */
-describe('AiChatService.stream — concurrent-run race rejection (#184)', () => {
-  const streamTextMock = streamText as unknown as jest.Mock;
-  const generateTextMock = generateText as unknown as jest.Mock;
-
-  beforeEach(() => {
-    streamTextMock.mockReset();
-    generateTextMock.mockReset();
-  });
-
-  // Minimal service whose only reachable deps before begin() are aiChatRepo
-  // (resolve the existing chat) — everything past begin must remain untouched.
-  function makeService(beginImpl: () => Promise<unknown>) {
-    const aiChatMessageRepo = { insert: jest.fn() };
-    const aiChatRepo = {
-      // An existing chat: stream keeps the supplied chatId and skips creation.
-      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
-      insert: jest.fn(),
-    };
-    const svc = new AiChatService(
-      {} as never, // ai
-      aiChatRepo as never,
-      aiChatMessageRepo as never,
-      {} as never, // aiChatPageSnapshotRepo
-      {} as never, // aiSettings
-      {} as never, // tools
-      {} as never, // mcpClients
-      {} as never, // aiAgentRoleRepo
-      {} as never, // pageRepo
-      {} as never, // pageAccess
-    );
-    const begin = jest.fn(beginImpl);
-    return { svc, begin, aiChatRepo, aiChatMessageRepo };
-  }
-
-  const baseArgs = (begin: jest.Mock) => ({
-    user: { id: 'user-1' } as never,
-    workspace: { id: 'ws-1' } as never,
-    sessionId: 'sess-1',
-    body: { chatId: 'chat-1', messages: [] } as never,
-    res: { raw: {} } as never,
-    signal: new AbortController().signal,
-    model: {} as never,
-    role: null,
-    runHooks: {
-      begin,
-      onAssistantSeeded: jest.fn(),
-      onStep: jest.fn(),
-      onSettled: jest.fn(),
-    } as never,
-  });
-
-  it('rejects the racer with a 409 ConflictException BEFORE any AI call, and never persists an untracked turn', async () => {
-    // begin loses the unique-index race -> RunAlreadyActiveError.
-    const { svc, begin, aiChatMessageRepo } = makeService(() => {
-      throw new RunAlreadyActiveError('chat-1');
-    });
-
-    const promise = svc.stream(baseArgs(begin));
-
-    await expect(promise).rejects.toBeInstanceOf(ConflictException);
-    await promise.catch((err: ConflictException) => {
-      expect(err.getStatus()).toBe(409);
-      expect((err.getResponse() as { code?: string }).code).toBe(
-        'A_RUN_ALREADY_ACTIVE',
-      );
-    });
-
-    // The decisive assertions: the rejected racer spent NO tokens and left NO
-    // untracked turn behind.
-    expect(begin).toHaveBeenCalledTimes(1);
-    expect(streamTextMock).not.toHaveBeenCalled();
-    expect(generateTextMock).not.toHaveBeenCalled();
-    expect(aiChatMessageRepo.insert).not.toHaveBeenCalled();
-  });
-});
-
-/**
- * F3 — the LOAD-BEARING run-detach wiring: `effectiveSignal = handle.signal`
- * after runHooks.begin, then `abortSignal: effectiveSignal` passed to streamText.
- * That single line is what makes a run survive a browser disconnect (the agent
- * loop's abort is governed by the RUN's signal, not the socket): a regression to
- * the socket-bound signal would still pass every other test green while silently
- * breaking Stop + durability. These two tests pin the exact signal streamText
- * consumes on both paths.
- */
-describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
-  const streamTextMock = streamText as unknown as jest.Mock;
-
-  // A streamText result stub: the post-call drain + pipe are no-ops here; we only
-  // care WHICH abortSignal streamText was handed.
-  function makeStreamResult() {
-    return {
-      consumeStream: jest.fn(),
-      pipeUIMessageStreamToResponse: jest.fn(),
-    };
-  }
-
-  // A raw-response stub sufficient for the post-streamText wiring
-  // (stripStreamingHopByHopHeaders binds writeHead; startSseHeartbeat registers
-  // close/finish listeners; flushHeaders is belt-and-braces).
-  function makeRes() {
-    return {
-      raw: {
-        writeHead: jest.fn(),
-        write: jest.fn(),
-        once: jest.fn(),
-        on: jest.fn(),
-        flushHeaders: jest.fn(),
-        writableEnded: false,
-        destroyed: false,
-      },
-    };
-  }
-
-  // Wire only the deps reached on the way to streamText: resolve the existing
-  // chat, persist the user + seed the assistant row, load (empty) history, the
-  // admin settings, an empty external toolset + Docmost toolset.
-  function makeService() {
-    const aiChatRepo = {
-      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
-      insert: jest.fn(),
-    };
-    const aiChatMessageRepo = {
-      insert: jest.fn(async () => ({ id: 'msg-1' })),
-      findAllByChat: jest.fn(async () => []),
-      update: jest.fn(async () => ({ id: 'msg-1' })),
-    };
-    const aiSettings = { resolve: jest.fn(async () => ({})) };
-    const tools = { forUser: jest.fn(async () => ({})) };
-    const mcpClients = {
-      toolsFor: jest.fn(async () => ({
-        tools: {},
-        clients: [],
-        outcomes: [],
-        instructions: [],
-      })),
-    };
-    const svc = new AiChatService(
-      {} as never, // ai
-      aiChatRepo as never,
-      aiChatMessageRepo as never,
-      {} as never, // aiChatPageSnapshotRepo
-      aiSettings as never,
-      tools as never,
-      mcpClients as never,
-      {} as never, // aiAgentRoleRepo
-      {} as never, // pageRepo (openPage undefined -> never touched)
-      {} as never, // pageAccess
-    );
-    return { svc };
-  }
-
-  const body = {
-    chatId: 'chat-1',
-    messages: [
-      { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
-    ],
-  };
-
-  beforeEach(() => {
-    streamTextMock.mockReset();
-    streamTextMock.mockImplementation(() => makeStreamResult());
-    jest
-      .spyOn(Logger.prototype, 'log')
-      .mockImplementation(() => undefined as never);
-  });
-
-  afterEach(() => jest.restoreAllMocks());
-
-  it('happy path (run-wrapped): streamText is driven with abortSignal === handle.signal (the RUN signal, NOT the socket)', async () => {
-    const { svc } = makeService();
-    const runController = new AbortController();
-    const runSignal = runController.signal;
-    const socketSignal = new AbortController().signal;
-
-    const begin = jest.fn(async () => ({ runId: 'run-1', signal: runSignal }));
-    await svc.stream({
-      user: { id: 'user-1' } as never,
-      workspace: { id: 'ws-1' } as never,
-      sessionId: 'sess-1',
-      body: body as never,
-      res: makeRes() as never,
-      signal: socketSignal,
-      model: {} as never,
-      role: null,
-      runHooks: {
-        begin,
-        onAssistantSeeded: jest.fn(),
-        onStep: jest.fn(),
-        onSettled: jest.fn(),
-      } as never,
-    });
-
-    expect(begin).toHaveBeenCalledTimes(1);
-    expect(streamTextMock).toHaveBeenCalledTimes(1);
-    // THE assertion: the agent loop's abort is wired to the RUN, so a browser
-    // disconnect (which aborts only `socketSignal`) cannot end the turn.
-    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(runSignal);
-    expect(streamTextMock.mock.calls[0][0].abortSignal).not.toBe(socketSignal);
-  });
-
-  it('legacy path (no runHooks): streamText is driven with the SOCKET signal', async () => {
-    const { svc } = makeService();
-    const socketSignal = new AbortController().signal;
-
-    await svc.stream({
-      user: { id: 'user-1' } as never,
-      workspace: { id: 'ws-1' } as never,
-      sessionId: 'sess-1',
-      body: body as never,
-      res: makeRes() as never,
-      signal: socketSignal,
-      model: {} as never,
-      role: null,
-      // No runHooks -> the turn stays socket-bound (flag off / default).
-    });
-
-    expect(streamTextMock).toHaveBeenCalledTimes(1);
-    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(socketSignal);
-  });
-
-  /**
-   * F9 — streamText's TERMINAL callbacks carry the #184 run lifecycle:
-   *   onStepFinish -> runHooks.onStep(runId, stepCount)
-   *   onFinish     -> runHooks.onSettled(runId, 'completed')   (dominant path)
-   *   onAbort      -> runHooks.onSettled(runId, 'aborted')
-   *   onError      -> runHooks.onSettled(runId, 'error', cause)
-   * makeStreamResult() ignores the streamText options, so these callbacks never
-   * fire on their own — a regression in this wiring (esp. the success path) would
-   * strand the run with NO test catching it. Here we CAPTURE the options streamText
-   * was handed and invoke each callback with the real wiring, asserting the run
-   * hooks fire with the right args.
-   */
-  // Drive stream() to the point streamText is called, capturing the options object
-  // (which carries onStepFinish/onFinish/onError/onAbort) and the run hooks.
-  async function captureStreamCallbacks() {
-    const { svc } = makeService();
-    let capturedOpts: any;
-    streamTextMock.mockImplementation((opts: any) => {
-      capturedOpts = opts;
-      return makeStreamResult();
-    });
-    const runHooks = {
-      begin: jest.fn(async () => ({
-        runId: 'run-1',
-        signal: new AbortController().signal,
-      })),
-      onAssistantSeeded: jest.fn(),
-      onStep: jest.fn(),
-      onSettled: jest.fn(),
-    };
-    await svc.stream({
-      user: { id: 'user-1' } as never,
-      workspace: { id: 'ws-1' } as never,
-      sessionId: 'sess-1',
-      body: body as never,
-      res: makeRes() as never,
-      signal: new AbortController().signal,
-      model: {} as never,
-      role: null,
-      runHooks: runHooks as never,
-    });
-    expect(capturedOpts).toBeDefined();
-    return { capturedOpts, runHooks };
-  }
-
-  it('F9: onStepFinish bumps the run step count, onFinish settles the run "completed" (the dominant autonomous-run path)', async () => {
-    const { capturedOpts, runHooks } = await captureStreamCallbacks();
-
-    // A finished step -> onStep(runId, finishedStepCount).
-    capturedOpts.onStepFinish({ text: 'step one', toolCalls: [], content: [] });
-    expect(runHooks.onStep).toHaveBeenCalledWith('run-1', 1);
-    capturedOpts.onStepFinish({ text: 'step two', toolCalls: [], content: [] });
-    expect(runHooks.onStep).toHaveBeenLastCalledWith('run-1', 2);
-
-    // The success terminal callback settles the run.
-    await capturedOpts.onFinish({
-      text: 'done',
-      finishReason: 'stop',
-      totalUsage: {},
-      usage: {},
-      steps: [],
-    });
-    expect(runHooks.onSettled).toHaveBeenCalledWith('run-1', 'completed');
-  });
-
-  it('F9: onAbort settles the run "aborted"', async () => {
-    jest
-      .spyOn(Logger.prototype, 'warn')
-      .mockImplementation(() => undefined as never);
-    const { capturedOpts, runHooks } = await captureStreamCallbacks();
-
-    await capturedOpts.onAbort({ steps: [] });
-    expect(runHooks.onSettled).toHaveBeenCalledWith('run-1', 'aborted');
-  });
-
-  it('F9: onError settles the run "error" carrying the provider cause', async () => {
-    jest
-      .spyOn(Logger.prototype, 'error')
-      .mockImplementation(() => undefined as never);
-    jest
-      .spyOn(Logger.prototype, 'warn')
-      .mockImplementation(() => undefined as never);
-    const { capturedOpts, runHooks } = await captureStreamCallbacks();
-
-    await capturedOpts.onError({ error: new Error('provider exploded') });
-    expect(runHooks.onSettled).toHaveBeenCalledWith(
-      'run-1',
-      'error',
-      expect.stringContaining('provider exploded'),
-    );
-  });
-});
-
-/**
- * F14 — the begin-failure RESILIENCE branch (the `else` of the run-race guard).
- *
- * stream() wraps runHooks.begin in try/catch with TWO branches:
- *   - RunAlreadyActiveError  -> 409 ConflictException (pinned above).
- *   - ANY OTHER begin failure -> SWALLOW + continue UNTRACKED on the socket signal
- *     (legacy fallback): it logs "...streaming without run tracking", leaves
- *     `effectiveSignal = signal` (runId undefined) and serves the turn anyway.
- *
- * The contract: a transient beginRun failure (e.g. a non-unique DB error inserting
- * the run row) must STILL serve the user's turn — it must NOT re-throw and must NOT
- * be misclassified as a 409. A regression that re-threw here would break EVERY turn
- * on a begin failure with nothing to catch it. This branch is otherwise undriven by
- * any spec, so it is pinned here SEPARATELY from the 409 path: a plain begin error
- * proceeds to streamText with the SOCKET signal and still persists the user turn.
- */
-describe('AiChatService.stream — begin-failure resilience / legacy fallback (#184 F14)', () => {
-  const streamTextMock = streamText as unknown as jest.Mock;
-
-  function makeStreamResult() {
-    return {
-      consumeStream: jest.fn(),
-      pipeUIMessageStreamToResponse: jest.fn(),
-    };
-  }
-
-  function makeRes() {
-    return {
-      raw: {
-        writeHead: jest.fn(),
-        write: jest.fn(),
-        once: jest.fn(),
-        on: jest.fn(),
-        flushHeaders: jest.fn(),
-        writableEnded: false,
-        destroyed: false,
-      },
-    };
-  }
-
-  // Same harness as the F3 abortSignal block, but it also exposes
-  // aiChatMessageRepo so we can assert the user turn IS persisted (the turn really
-  // streamed) despite begin() blowing up.
-  function makeService() {
-    const aiChatRepo = {
-      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
-      insert: jest.fn(),
-    };
-    const aiChatMessageRepo = {
-      insert: jest.fn(async () => ({ id: 'msg-1' })),
-      findAllByChat: jest.fn(async () => []),
-      update: jest.fn(async () => ({ id: 'msg-1' })),
-    };
-    const aiSettings = { resolve: jest.fn(async () => ({})) };
-    const tools = { forUser: jest.fn(async () => ({})) };
-    const mcpClients = {
-      toolsFor: jest.fn(async () => ({
-        tools: {},
-        clients: [],
-        outcomes: [],
-        instructions: [],
-      })),
-    };
-    const svc = new AiChatService(
-      {} as never, // ai
-      aiChatRepo as never,
-      aiChatMessageRepo as never,
-      {} as never, // aiChatPageSnapshotRepo
-      aiSettings as never,
-      tools as never,
-      mcpClients as never,
-      {} as never, // aiAgentRoleRepo
-      {} as never, // pageRepo
-      {} as never, // pageAccess
-    );
-    return { svc, aiChatMessageRepo };
-  }
-
-  const body = {
-    chatId: 'chat-1',
-    messages: [
-      { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
-    ],
-  };
-
-  beforeEach(() => {
-    streamTextMock.mockReset();
-    streamTextMock.mockImplementation(() => makeStreamResult());
-    jest
-      .spyOn(Logger.prototype, 'log')
-      .mockImplementation(() => undefined as never);
-  });
-
-  afterEach(() => jest.restoreAllMocks());
-
-  it('a PLAIN begin() failure (NOT RunAlreadyActiveError) does NOT 409 — it swallows, logs, and streams the turn UNTRACKED on the socket signal', async () => {
-    const errorSpy = jest
-      .spyOn(Logger.prototype, 'error')
-      .mockImplementation(() => undefined as never);
-
-    const { svc, aiChatMessageRepo } = makeService();
-    const socketSignal = new AbortController().signal;
-
-    // A transient, NON-race begin failure (e.g. a non-unique DB error inserting
-    // the run row). This is the `else` branch of the begin try/catch.
-    const begin = jest.fn(async () => {
-      throw new Error('insert failed');
-    });
-
-    const promise = svc.stream({
-      user: { id: 'user-1' } as never,
-      workspace: { id: 'ws-1' } as never,
-      sessionId: 'sess-1',
-      body: body as never,
-      res: makeRes() as never,
-      signal: socketSignal,
-      model: {} as never,
-      role: null,
-      runHooks: {
-        begin,
-        onAssistantSeeded: jest.fn(),
-        onStep: jest.fn(),
-        onSettled: jest.fn(),
-      } as never,
-    });
-
-    // The turn proceeds: NO throw at all (in particular NOT a 409).
-    await expect(promise).resolves.toBeUndefined();
-
-    expect(begin).toHaveBeenCalledTimes(1);
-
-    // The resilience branch logged the legacy-fallback warning.
-    expect(errorSpy).toHaveBeenCalledWith(
-      expect.stringContaining('streaming without run tracking'),
-      expect.anything(),
-    );
-
-    // The turn really streamed: the user message was persisted and streamText ran.
-    expect(aiChatMessageRepo.insert).toHaveBeenCalled();
-    expect(streamTextMock).toHaveBeenCalledTimes(1);
-
-    // The decisive wiring: with no run handle, the fallback uses the SOCKET signal
-    // (effectiveSignal = signal, runId undefined) — not a run-bound signal.
-    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(socketSignal);
-  });
-});

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);
+  });
 });
 
 /**
@@ -372,12 +398,6 @@ describe('chatStreamMetadata', () => {
     });
   });
 
-  it('attaches the runId on the start part when a run wraps the turn (#184)', () => {
-    expect(
-      chatStreamMetadata({ type: 'start' }, 'chat-1', undefined, 'run-1'),
-    ).toEqual({ chatId: 'chat-1', runId: 'run-1' });
-  });
-
   it('returns the CUMULATIVE step usage passed in for the finish-step part', () => {
     // finish-step usage is per-step in v6; the caller accumulates and passes the
     // running sum, which this just wraps.

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/dto/ai-chat.dto.ts

@@ -43,30 +43,6 @@ export class BoundChatDto {
   pageId: string;
 }
 
-/**
- * Reconnect to the latest run of a chat (#184): fetch its persisted lifecycle
- * state (and the assistant message it projects) for an in-flight or finished run.
- */
-export class GetRunDto {
-  @IsString()
-  chatId: string;
-}
-
-/**
- * Explicitly STOP an agent run (#184): the user pressed Stop — distinct from a
- * browser disconnect, which never stops a run. Either the run id (preferred, from
- * the streamed start metadata) or the chat id (stop whatever run is active on it).
- */
-export class StopRunDto {
-  @IsOptional()
-  @IsString()
-  runId?: string;
-
-  @IsOptional()
-  @IsString()
-  chatId?: string;
-}
-
 /** Export a chat to Markdown (#183). `lang` localizes the few fixed
  *  role/tool-action labels; defaults to English server-side. */
 export class ExportChatDto {

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

@@ -0,0 +1,237 @@
+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 service = new CommentService(
+      commentRepo,
+      pageRepo,
+      wsService,
+      collaborationGateway,
+      generalQueue,
+      notificationQueue,
+    );
+
+    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.ts

@@ -207,17 +207,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(

apps/server/src/core/workspace/dto/update-workspace.dto.ts

@@ -55,14 +55,6 @@ export class UpdateWorkspaceDto extends PartialType(CreateWorkspaceDto) {
   @IsBoolean()
   aiDictationStreaming: boolean;
 
-  // #184: detached/autonomous agent runs (settings.ai.autonomousRuns). When on, a
-  // chat turn becomes a server-side RUN that survives a browser disconnect; only
-  // an explicit /ai-chat/stop ends it. Off by default; single-instance-only in
-  // phase 1 (see AiChatRunService.warnIfMultiInstance / AGENTS.md).
-  @IsOptional()
-  @IsBoolean()
-  autonomousRuns: boolean;
-
   // Workspace master toggle that enables/disables the HTML embed block type.
   // Persisted at settings.htmlEmbed. ABSENT/false => OFF (default). The block
   // itself renders in a sandboxed iframe, so this is a feature switch, not a

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

@@ -526,20 +526,6 @@ export class WorkspaceService {
         );
       }
 
-      if (typeof updateWorkspaceDto.autonomousRuns !== 'undefined') {
-        const prev = settingsBefore?.ai?.autonomousRuns ?? false;
-        if (prev !== updateWorkspaceDto.autonomousRuns) {
-          before.autonomousRuns = prev;
-          after.autonomousRuns = updateWorkspaceDto.autonomousRuns;
-        }
-        await this.workspaceRepo.updateAiSettings(
-          workspaceId,
-          'autonomousRuns',
-          updateWorkspaceDto.autonomousRuns,
-          trx,
-        );
-      }
-
       if (typeof updateWorkspaceDto.htmlEmbed !== 'undefined') {
         const prev = settingsBefore?.htmlEmbed ?? false;
         if (prev !== updateWorkspaceDto.htmlEmbed) {
@@ -593,7 +579,6 @@ export class WorkspaceService {
       delete updateWorkspaceDto.aiChat;
       delete updateWorkspaceDto.aiDictation;
       delete updateWorkspaceDto.aiDictationStreaming;
-      delete updateWorkspaceDto.autonomousRuns;
       delete updateWorkspaceDto.htmlEmbed;
       delete updateWorkspaceDto.trackerHead;
       delete updateWorkspaceDto.aiPublicShareAssistant;

apps/server/src/database/database.module.ts

@@ -31,7 +31,6 @@ import { FavoriteRepo } from '@docmost/db/repos/favorite/favorite.repo';
 import { TemplateRepo } from '@docmost/db/repos/template/template.repo';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
-import { AiChatRunRepo } from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
 import { AiChatPageSnapshotRepo } from '@docmost/db/repos/ai-chat/ai-chat-page-snapshot.repo';
 import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider-credentials.repo';
 import { AiMcpServerRepo } from '@docmost/db/repos/ai-chat/ai-mcp-server.repo';
@@ -106,7 +105,6 @@ import { normalizePostgresUrl } from '../common/helpers';
     TemplateRepo,
     AiChatRepo,
     AiChatMessageRepo,
-    AiChatRunRepo,
     AiChatPageSnapshotRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,
@@ -141,7 +139,6 @@ import { normalizePostgresUrl } from '../common/helpers';
     TemplateRepo,
     AiChatRepo,
     AiChatMessageRepo,
-    AiChatRunRepo,
     AiChatPageSnapshotRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,

apps/server/src/database/migrations/20260627T130000-ai-chat-runs.ts

@@ -1,106 +0,0 @@
-import { type Kysely, sql } from 'kysely';
-
-/**
- * `ai_chat_runs` — the agent RUN as a first-class, server-side lifecycle object
- * (#184 phase 1: autonomous agent runs detached from the browser window).
- *
- * Until now an agent turn lived ONLY as long as the HTTP request was open
- * (`res.hijack()` in ai-chat.controller.ts); a browser disconnect aborted it.
- * This table makes a turn a persistent object the server owns: it is created
- * when a run starts (inserted directly as 'running' in phase 1 — 'pending' is
- * only this column's default + a reserved value, never written by code yet) and
- * advances to succeeded|failed|aborted, surviving the subscriber (browser) going
- * away when it settles. The DB is the source of
- * truth — a later client reconnects/sees the result by reading this row plus the
- * assistant message it projects (`assistant_message_id`).
- *
- * The assistant message row (#183 step-granular durability) is the PROJECTION of
- * a run's output; this row is the run's LIFECYCLE. They are linked by
- * `assistant_message_id` (SET NULL if the message is later pruned).
- *
- * `status`  : 'pending' | 'running' | 'succeeded' | 'failed' | 'aborted'.
- * `trigger` : 'user' | 'autostart' | 'schedule' | 'api' | 'continue' — only
- *             'user' is produced in phase 1; the others are reserved for the
- *             autonomy triggers deferred to phase 2 so they need no later
- *             migration.
- *
- * ONE ACTIVE RUN PER CHAT is enforced by a partial unique index on `chat_id`
- * WHERE status IN ('pending','running'): an autonomous run and a user run can
- * never trample each other on the same chat. Settled runs (succeeded/failed/
- * aborted) are excluded from the index so a chat can accumulate any number of
- * historical runs.
- */
-export async function up(db: Kysely<any>): Promise<void> {
-  await db.schema
-    .createTable('ai_chat_runs')
-    .ifNotExists()
-    .addColumn('id', 'uuid', (col) =>
-      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
-    )
-    .addColumn('chat_id', 'uuid', (col) =>
-      col.references('ai_chats.id').onDelete('cascade').notNull(),
-    )
-    .addColumn('workspace_id', 'uuid', (col) =>
-      col.references('workspaces.id').onDelete('cascade').notNull(),
-    )
-    // The human who triggered the run (audit). SET NULL on user deletion so the
-    // run history outlives its author; NULL is also the natural value for a
-    // future system/cron/api trigger with no human actor.
-    .addColumn('created_by', 'uuid', (col) =>
-      col.references('users.id').onDelete('set null'),
-    )
-    // The assistant message this run materializes (the #183 projection). SET NULL
-    // if that message row is later deleted; nullable because the run row is
-    // created a moment BEFORE the assistant row is seeded.
-    .addColumn('assistant_message_id', 'uuid', (col) =>
-      col.references('ai_chat_messages.id').onDelete('set null'),
-    )
-    .addColumn('trigger', 'varchar(20)', (col) =>
-      col.notNull().defaultTo('user'),
-    )
-    .addColumn('status', 'varchar(20)', (col) =>
-      col.notNull().defaultTo('pending'),
-    )
-    // Terminal error message for a failed run (provider/transport cause),
-    // mirroring the assistant message's metadata.error.
-    .addColumn('error', 'text', (col) => col)
-    // Number of agent steps finished so far (kept monotonic with the projection).
-    .addColumn('step_count', 'integer', (col) => col.notNull().defaultTo(0))
-    // Set when an EXPLICIT user stop is requested (distinct from a mere browser
-    // disconnect, which never stops a run). The runner aborts the turn and the
-    // run settles as 'aborted'.
-    .addColumn('stop_requested_at', 'timestamptz', (col) => col)
-    .addColumn('started_at', 'timestamptz', (col) => col)
-    .addColumn('finished_at', 'timestamptz', (col) => col)
-    .addColumn('created_at', 'timestamptz', (col) =>
-      col.notNull().defaultTo(sql`now()`),
-    )
-    .addColumn('updated_at', 'timestamptz', (col) =>
-      col.notNull().defaultTo(sql`now()`),
-    )
-    .execute();
-
-  // Reconnect / "latest run for this chat" reads hit chat_id first.
-  await db.schema
-    .createIndex('ai_chat_runs_chat_id_idx')
-    .ifNotExists()
-    .on('ai_chat_runs')
-    .column('chat_id')
-    .execute();
-
-  // One ACTIVE run per chat (advisory at the DB level): a second pending/running
-  // run on the same chat is rejected, so a user turn and an autonomous turn can
-  // never race on the same chat. Partial so settled runs do not collide.
-  await db.schema
-    .createIndex('ai_chat_runs_one_active_per_chat')
-    .ifNotExists()
-    .on('ai_chat_runs')
-    .column('chat_id')
-    .unique()
-    .where(sql.ref('status'), 'in', sql`('pending','running')`)
-    .execute();
-}
-
-export async function down(db: Kysely<any>): Promise<void> {
-  await db.schema.dropTable('ai_chat_runs').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/ai-chat/ai-chat-message.repo.ts

@@ -121,23 +121,6 @@ export class AiChatMessageRepo {
     return rows.reverse();
   }
 
-  /** Fetch a single message by id + workspace (e.g. a run's projection row for
-   *  the #184 reconnect read). Returns undefined when nothing matches. */
-  async findById(
-    id: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<AiChatMessage | undefined> {
-    const db = dbOrTx(this.db, trx);
-    return db
-      .selectFrom('aiChatMessages')
-      .select(this.baseFields)
-      .where('id', '=', id)
-      .where('workspaceId', '=', workspaceId)
-      .where('deletedAt', 'is', null)
-      .executeTakeFirst();
-  }
-
   async insert(
     insertable: InsertableAiChatMessage,
     trx?: KyselyTransaction,

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

@@ -1,82 +0,0 @@
-import { AiChatRunRepo, SWEEP_RUN_STALE_MS } from './ai-chat-run.repo';
-import type { KyselyDB } from '../../types/kysely.types';
-
-/**
- * Unit coverage for AiChatRunRepo.sweepRunning over a chainable builder mock (no
- * live DB). The F1 invariant under test (DECISION C): the BOOT sweep is
- * UNCONDITIONAL — it adds NO `updatedAt <` predicate, so a fresh 'running' run
- * (updatedAt = now) IS settled rather than skipped by a staleness window. The
- * window is added ONLY when an explicit `staleMs` is supplied (the future phase-2
- * multi-instance timer sweep). We assert the EXACT predicates the spec mandates.
- */
-describe('AiChatRunRepo.sweepRunning', () => {
-  type Recorded = {
-    table?: string;
-    set?: Record<string, unknown>;
-    wheres: Array<[string, string, unknown]>;
-    returning?: string;
-  };
-
-  function makeDb(swept: Array<{ id: string }>): {
-    db: KyselyDB;
-    rec: Recorded;
-  } {
-    const rec: Recorded = { wheres: [] };
-    const builder: Record<string, unknown> = {};
-    builder.set = (v: Record<string, unknown>) => {
-      rec.set = v;
-      return builder;
-    };
-    builder.where = (col: string, op: string, val: unknown) => {
-      rec.wheres.push([col, op, val]);
-      return builder;
-    };
-    builder.returning = (col: string) => {
-      rec.returning = col;
-      return builder;
-    };
-    builder.execute = () => Promise.resolve(swept);
-    const db = {
-      updateTable: (table: string) => {
-        rec.table = table;
-        return builder;
-      },
-    } as unknown as KyselyDB;
-    return { db, rec };
-  }
-
-  it('F1: the boot sweep (no staleMs) is UNCONDITIONAL — only a status filter, NO updatedAt window', async () => {
-    const { db, rec } = makeDb([{ id: 'r1' }, { id: 'r2' }]);
-    const repo = new AiChatRunRepo(db);
-
-    const swept = await repo.sweepRunning();
-
-    expect(swept).toBe(2);
-    expect(rec.table).toBe('aiChatRuns');
-    // The status filter is always present...
-    expect(rec.wheres).toContainEqual([
-      'status',
-      'in',
-      expect.arrayContaining(['pending', 'running']),
-    ]);
-    // ...but a fresh 'running' run (updatedAt = now) must NOT be skipped: no
-    // updatedAt predicate at all on the boot path.
-    expect(rec.wheres.some(([col]) => col === 'updatedAt')).toBe(false);
-    // It flips to 'aborted' and stamps finishedAt.
-    expect(rec.set).toEqual(
-      expect.objectContaining({ status: 'aborted', finishedAt: expect.any(Date) }),
-    );
-  });
-
-  it('phase-2 path: an explicit staleMs reintroduces the updatedAt window', async () => {
-    const { db, rec } = makeDb([]);
-    const repo = new AiChatRunRepo(db);
-
-    await repo.sweepRunning({ staleMs: SWEEP_RUN_STALE_MS });
-
-    const updatedAtWhere = rec.wheres.find(([col]) => col === 'updatedAt');
-    expect(updatedAtWhere).toBeDefined();
-    expect(updatedAtWhere![1]).toBe('<');
-    expect(updatedAtWhere![2]).toBeInstanceOf(Date);
-  });
-});

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

@@ -1,212 +0,0 @@
-import { Injectable, Logger } from '@nestjs/common';
-import { InjectKysely } from 'nestjs-kysely';
-import { sql } from 'kysely';
-import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx } from '../../utils';
-import {
-  AiChatRun,
-  InsertableAiChatRun,
-} from '@docmost/db/types/entity.types';
-
-// Statuses that count as "the run is still live" (an autonomous and a user run
-// must never both be live on one chat — enforced by the partial unique index and
-// checked here for friendly 409s before the insert races the constraint).
-export const ACTIVE_RUN_STATUSES = ['pending', 'running'] as const;
-
-// Crash-recovery sweep recency threshold (mirrors AiChatMessageRepo.sweepStreaming,
-// #183): when a staleness window is supplied, a 'running'/'pending' run is only
-// swept to 'aborted' once it has been UNTOUCHED for this long, so a sibling
-// replica's boot-sweep can never abort a run another replica is actively
-// executing. The runner bumps `updatedAt` on every step, so a live run never
-// matches. PHASE 1 is single-process and the boot sweep passes NO window (every
-// dangling run is settled unconditionally — see sweepRunning / F1). This constant
-// is the window to reintroduce for the phase-2 multi-instance timer sweep.
-export const SWEEP_RUN_STALE_MS = 10 * 60 * 1000; // 10 minutes
-
-/**
- * Repository for `ai_chat_runs` (#184 phase 1): the agent run as a first-class,
- * server-side lifecycle object detached from the HTTP request. The run row is the
- * point a client subscribes/reconnects to (by `id` or by chat); the assistant
- * message it links to (`assistantMessageId`) is the #183 projection of its output.
- */
-@Injectable()
-export class AiChatRunRepo {
-  private readonly logger = new Logger(AiChatRunRepo.name);
-
-  private baseFields: Array<keyof AiChatRun> = [
-    'id',
-    'chatId',
-    'workspaceId',
-    'createdBy',
-    'assistantMessageId',
-    'trigger',
-    'status',
-    'error',
-    'stepCount',
-    'stopRequestedAt',
-    'startedAt',
-    'finishedAt',
-    'createdAt',
-    'updatedAt',
-  ];
-
-  constructor(@InjectKysely() private readonly db: KyselyDB) {}
-
-  async insert(
-    insertable: InsertableAiChatRun,
-    trx?: KyselyTransaction,
-  ): Promise<AiChatRun> {
-    const db = dbOrTx(this.db, trx);
-    return db
-      .insertInto('aiChatRuns')
-      .values(insertable)
-      .returning(this.baseFields)
-      .executeTakeFirst();
-  }
-
-  async findById(
-    id: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<AiChatRun | undefined> {
-    const db = dbOrTx(this.db, trx);
-    return db
-      .selectFrom('aiChatRuns')
-      .select(this.baseFields)
-      .where('id', '=', id)
-      .where('workspaceId', '=', workspaceId)
-      .executeTakeFirst();
-  }
-
-  /** The currently-active (pending|running) run for a chat, if any. At most one
-   *  exists thanks to the partial unique index. */
-  async findActiveByChat(
-    chatId: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<AiChatRun | undefined> {
-    const db = dbOrTx(this.db, trx);
-    return db
-      .selectFrom('aiChatRuns')
-      .select(this.baseFields)
-      .where('chatId', '=', chatId)
-      .where('workspaceId', '=', workspaceId)
-      .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[])
-      .executeTakeFirst();
-  }
-
-  /** The most-recent run for a chat (active or settled) — the reconnect target. */
-  async findLatestByChat(
-    chatId: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<AiChatRun | undefined> {
-    const db = dbOrTx(this.db, trx);
-    return db
-      .selectFrom('aiChatRuns')
-      .select(this.baseFields)
-      .where('chatId', '=', chatId)
-      .where('workspaceId', '=', workspaceId)
-      .orderBy('createdAt', 'desc')
-      .orderBy('id', 'desc')
-      .limit(1)
-      .executeTakeFirst();
-  }
-
-  /**
-   * Patch a run by id + workspace; always bumps `updatedAt`. Used for every
-   * lifecycle transition (mark running, link the assistant message, bump
-   * step_count, finalize succeeded/failed/aborted). Returns the updated row or
-   * undefined when nothing matched (e.g. a foreign workspace).
-   */
-  async update(
-    id: string,
-    workspaceId: string,
-    patch: Partial<{
-      status: string;
-      error: string | null;
-      stepCount: number;
-      assistantMessageId: string | null;
-      stopRequestedAt: Date | null;
-      startedAt: Date | null;
-      finishedAt: Date | null;
-    }>,
-    trx?: KyselyTransaction,
-  ): Promise<AiChatRun | undefined> {
-    const db = dbOrTx(this.db, trx);
-    return db
-      .updateTable('aiChatRuns')
-      .set({ ...(patch as Record<string, unknown>), updatedAt: new Date() })
-      .where('id', '=', id)
-      .where('workspaceId', '=', workspaceId)
-      .returning(this.baseFields)
-      .executeTakeFirst();
-  }
-
-  /**
-   * Mark an EXPLICIT stop request on an active run (distinct from a browser
-   * disconnect, which never stops a run). Stamps `stop_requested_at` ONLY while
-   * the run is still active, so a late stop on an already-settled run is a no-op.
-   * Returns the row when a stop was recorded, else undefined (nothing active).
-   */
-  async markStopRequested(
-    id: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<AiChatRun | undefined> {
-    const db = dbOrTx(this.db, trx);
-    return db
-      .updateTable('aiChatRuns')
-      .set({ stopRequestedAt: new Date(), updatedAt: new Date() })
-      .where('id', '=', id)
-      .where('workspaceId', '=', workspaceId)
-      .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[])
-      .returning(this.baseFields)
-      .executeTakeFirst();
-  }
-
-  /**
-   * Crash-recovery sweep (mirrors AiChatMessageRepo.sweepStreaming): flip every
-   * run still left pending/running — a run whose process died before reaching a
-   * terminal status — to 'aborted', stamping `finished_at`. Returns the number
-   * swept. Workspace-wide on purpose (a crash can dangle runs in any workspace).
-   *
-   * F1 (DECISION C): the BOOT sweep is UNCONDITIONAL — it passes no `staleMs`, so
-   * EVERY dangling run is settled regardless of how recently it was touched. On a
-   * fresh single-process boot any pending|running run is definitionally hung (no
-   * runner is alive to own it), so a fast restart (deploy/OOM within minutes of
-   * the last step) no longer leaves a run stuck 'running' forever — which would
-   * make the one-active-run gate 409 every future turn in that chat.
-   *
-   * The optional `staleMs` window is reintroduced ONLY for the future phase-2
-   * multi-instance timer sweep (see {@link SWEEP_RUN_STALE_MS}): there a booting
-   * replica must NOT abort a run another replica is actively executing, so it
-   * sweeps only runs UNTOUCHED past the window. Phase 1 is single-process, so the
-   * boot path supplies no window.
-   */
-  async sweepRunning(
-    opts: { staleMs?: number } = {},
-    trx?: KyselyTransaction,
-  ): Promise<number> {
-    const db = dbOrTx(this.db, trx);
-    const now = new Date();
-    let query = db
-      .updateTable('aiChatRuns')
-      .set({
-        status: 'aborted',
-        finishedAt: now,
-        updatedAt: now,
-        error: sql`coalesce(error, ${'Run interrupted by a server restart.'})`,
-      })
-      .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[]);
-    // Multi-instance (phase 2) only: skip runs touched within the window so a
-    // sibling replica's live run is never aborted. Omitted on the phase-1 boot
-    // sweep -> unconditional.
-    if (typeof opts.staleMs === 'number') {
-      const staleBefore = new Date(now.getTime() - opts.staleMs);
-      query = query.where('updatedAt', '<', staleBefore);
-    }
-    const rows = await query.returning('id').execute();
-    return rows.length;
-  }
-}

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

@@ -644,35 +644,6 @@ export interface AiChatMessages {
   deletedAt: Timestamp | null;
 }
 
-// The agent RUN as a first-class server-side lifecycle object (#184 phase 1).
-// Mirrors migration 20260627T130000-ai-chat-runs.ts. A run is created when an
-// agent turn starts and survives the browser disconnecting; the DB is the source
-// of truth a later client reconnects to. `assistantMessageId` links to the #183
-// projection row (the assistant message this run materializes).
-export interface AiChatRuns {
-  id: Generated<string>;
-  chatId: string;
-  workspaceId: string;
-  // SET NULL on user deletion (the run history outlives its author); also NULL
-  // for a future non-human trigger (cron/api).
-  createdBy: string | null;
-  // The assistant message this run materializes; SET NULL if it is pruned.
-  assistantMessageId: string | null;
-  // 'user' | 'autostart' | 'schedule' | 'api' | 'continue' (only 'user' is
-  // produced in phase 1; the rest are reserved for the deferred autonomy triggers).
-  trigger: Generated<string>;
-  // 'pending' | 'running' | 'succeeded' | 'failed' | 'aborted'.
-  status: Generated<string>;
-  error: string | null;
-  stepCount: Generated<number>;
-  // Set when an EXPLICIT user stop is requested (distinct from a disconnect).
-  stopRequestedAt: Timestamp | null;
-  startedAt: Timestamp | null;
-  finishedAt: Timestamp | null;
-  createdAt: Generated<Timestamp>;
-  updatedAt: Generated<Timestamp>;
-}
-
 // Per-(chat,page) snapshot of the open page's Markdown at the END of the agent's
 // previous turn (#274). Mirrors migration 20260702T120000-ai-chat-page-snapshot.ts.
 // The next turn diffs the CURRENT Markdown against `contentMd` to surface edits a
@@ -709,7 +680,6 @@ export interface DB {
   aiAgentRoles: AiAgentRoles;
   aiChats: AiChats;
   aiChatMessages: AiChatMessages;
-  aiChatRuns: AiChatRuns;
   aiChatPageSnapshots: AiChatPageSnapshots;
   apiKeys: ApiKeys;
   attachments: Attachments;

apps/server/src/database/types/entity.types.ts

@@ -3,7 +3,6 @@ import {
   AiAgentRoles,
   AiChats,
   AiChatMessages,
-  AiChatRuns,
   AiChatPageSnapshots,
   Attachments,
   Comments,
@@ -57,12 +56,10 @@ export type UpdatableAiChat = Updateable<Omit<AiChats, 'id'>>;
 // full-text search. It is omitted from the public type so it never leaks
 // into HTTP responses or the chat history fed to the language model.
 export type AiChatMessage = Omit<Selectable<AiChatMessages>, 'tsv'>;
-export type InsertableAiChatMessage = Omit<Insertable<AiChatMessages>, 'tsv'>;
-
-// AI Chat Run (#184 phase 1): the agent run as a first-class lifecycle object,
-// detached from the HTTP request / browser window.
-export type AiChatRun = Selectable<AiChatRuns>;
-export type InsertableAiChatRun = Insertable<AiChatRuns>;
+export type InsertableAiChatMessage = Omit<
+  Insertable<AiChatMessages>,
+  'tsv'
+>;
 
 // AI Chat Page Snapshot (#274): per-(chat,page) Markdown snapshot taken at the
 // end of the agent's previous turn, diffed against the current page next turn to
@@ -217,14 +214,11 @@ export type UpdatableFavorite = Updateable<Omit<Favorites, 'id'>>;
 // Page Transclusion
 export type PageTransclusion = Selectable<PageTransclusions>;
 export type InsertablePageTransclusion = Insertable<PageTransclusions>;
-export type UpdatablePageTransclusion = Updateable<
-  Omit<PageTransclusions, 'id'>
->;
+export type UpdatablePageTransclusion = Updateable<Omit<PageTransclusions, 'id'>>;
 
 // Page Transclusion Reference
 export type PageTransclusionReference = Selectable<PageTransclusionReferences>;
-export type InsertablePageTransclusionReference =
-  Insertable<PageTransclusionReferences>;
+export type InsertablePageTransclusionReference = Insertable<PageTransclusionReferences>;
 export type UpdatablePageTransclusionReference = Updateable<
   Omit<PageTransclusionReferences, 'id'>
 >;
@@ -294,9 +288,7 @@ export type UpdatablePagePermission = Updateable<Omit<_PagePermissions, 'id'>>;
 // Page Verification
 export type PageVerification = Selectable<_PageVerifications>;
 export type InsertablePageVerification = Insertable<_PageVerifications>;
-export type UpdatablePageVerification = Updateable<
-  Omit<_PageVerifications, 'id'>
->;
+export type UpdatablePageVerification = Updateable<Omit<_PageVerifications, 'id'>>;
 
 // Page Verifier
 export type PageVerifier = Selectable<_PageVerifiers>;

apps/server/src/integrations/export/export-comment.spec.ts

@@ -0,0 +1,82 @@
+import { JSDOM } from 'jsdom';
+import { jsonToHtml } from '../../collaboration/collaboration.util';
+
+/**
+ * Regression test for issue #298: page/space export (Markdown/HTML) crashes on
+ * pages that contain inline comments.
+ *
+ * The in-process MCP module injects a jsdom `global.window` + `global.document`
+ * into the Node server (see packages/mcp/src/lib/collaboration.ts). Before the
+ * fix, the comment mark's `renderHTML` guard was only
+ * `typeof window === "undefined" || typeof document === "undefined"`, so with
+ * BOTH jsdom globals present it took the interactive browser branch and returned
+ * a LIVE jsdom <span> node. The export path serializes via happy-dom's
+ * DOMSerializer, and appending a foreign jsdom node crashed happy-dom
+ * ("Cannot read properties of undefined (reading 'length')").
+ *
+ * We reproduce the MCP-loaded server by injecting jsdom globals, then export a
+ * doc containing a comment mark and assert the serialization SUCCEEDS and emits
+ * the expected serializable <span data-comment-id=... class="comment-mark">.
+ *
+ * Non-vacuity: this test only exercises the buggy branch because BOTH jsdom
+ * `window` AND `document` are set below. If the `isNodeRuntime` condition is
+ * removed from the guard in packages/editor-ext/src/lib/comment/comment.ts,
+ * `renderHTML` returns a live jsdom node and `jsonToHtml` throws — this test
+ * then fails. (In a plain node env without the injected globals the guard's
+ * `typeof window === "undefined"` clause already short-circuits, so it is the
+ * injected globals that make this assertion meaningful.)
+ */
+describe('export with inline comments (issue #298)', () => {
+  const originalWindow = (global as any).window;
+  const originalDocument = (global as any).document;
+
+  beforeAll(() => {
+    const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+    (global as any).window = dom.window;
+    (global as any).document = dom.window.document;
+  });
+
+  afterAll(() => {
+    (global as any).window = originalWindow;
+    (global as any).document = originalDocument;
+  });
+
+  const docWithComment = (resolved: boolean) => ({
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: [
+          {
+            type: 'text',
+            marks: [
+              {
+                type: 'comment',
+                attrs: { commentId: 'c-123', resolved },
+              },
+            ],
+            text: 'commented text',
+          },
+        ],
+      },
+    ],
+  });
+
+  it('exports a page with an unresolved comment mark without crashing', () => {
+    let html: string;
+    expect(() => {
+      html = jsonToHtml(docWithComment(false));
+    }).not.toThrow();
+
+    expect(html).toContain('data-comment-id="c-123"');
+    expect(html).toContain('class="comment-mark"');
+    expect(html).toContain('commented text');
+  });
+
+  it('exports a resolved comment mark with the resolved class/attr', () => {
+    const html = jsonToHtml(docWithComment(true));
+    expect(html).toContain('data-comment-id="c-123"');
+    expect(html).toContain('comment-mark resolved');
+    expect(html).toContain('data-resolved="true"');
+  });
+});

apps/server/test/integration/ai-chat-run.int-spec.ts

@@ -1,304 +0,0 @@
-import { Kysely } from 'kysely';
-import {
-  AiChatRunRepo,
-  SWEEP_RUN_STALE_MS,
-} from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
-import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
-import { AiChatRunService } from '../../src/core/ai-chat/ai-chat-run.service';
-import {
-  getTestDb,
-  destroyTestDb,
-  createWorkspace,
-  createUser,
-  createChat,
-} from './db';
-
-/**
- * Integration coverage for the #184 phase-1 durable agent run: real SQL against
- * docmost_test. Proves the core invariant primitives — a run is a first-class
- * lifecycle row, at most one is active per chat, a detached run's progress
- * survives with NO subscriber, an explicit stop settles it as aborted, a
- * reconnect read returns the persisted state, and a crash sweep recovers
- * dangling runs.
- */
-describe('AiChatRun durable lifecycle [integration]', () => {
-  let db: Kysely<any>;
-  let runRepo: AiChatRunRepo;
-  let messageRepo: AiChatMessageRepo;
-  let service: AiChatRunService;
-  let workspaceId: string;
-  let otherWorkspaceId: string;
-  let userId: string;
-  let chatId: string;
-
-  beforeAll(async () => {
-    db = getTestDb();
-    runRepo = new AiChatRunRepo(db as any);
-    messageRepo = new AiChatMessageRepo(db as any);
-    // Boot-sweep isn't triggered here; the isCloud stub is all the service needs
-    // for these direct-call integration cases (F7).
-    service = new AiChatRunService(runRepo, { isCloud: () => false } as never);
-    workspaceId = (await createWorkspace(db)).id;
-    otherWorkspaceId = (await createWorkspace(db)).id;
-    userId = (await createUser(db, workspaceId)).id;
-    chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
-  });
-
-  afterAll(async () => {
-    await destroyTestDb();
-  });
-
-  // Each test that creates an active run settles it (or uses its own chat) so the
-  // partial unique index does not bleed across tests.
-
-  it('insert + findById round-trips a run row, defaulting status/trigger', async () => {
-    const run = await runRepo.insert({
-      chatId,
-      workspaceId,
-      createdBy: userId,
-    });
-    expect(run.status).toBe('pending');
-    expect(run.trigger).toBe('user');
-    expect(run.stepCount).toBe(0);
-
-    const found = await runRepo.findById(run.id, workspaceId);
-    expect(found!.id).toBe(run.id);
-    // Workspace-scoped: a foreign workspace sees nothing.
-    expect(await runRepo.findById(run.id, otherWorkspaceId)).toBeUndefined();
-
-    // settle so it does not occupy the active slot
-    await runRepo.update(run.id, workspaceId, {
-      status: 'succeeded',
-      finishedAt: new Date(),
-    });
-  });
-
-  it('enforces ONE ACTIVE run per chat (partial unique index rejects a second)', async () => {
-    const activeChat = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-    const first = await runRepo.insert({
-      chatId: activeChat,
-      workspaceId,
-      createdBy: userId,
-      status: 'running',
-    });
-    // A second pending/running run on the SAME chat must be rejected by the DB.
-    await expect(
-      runRepo.insert({
-        chatId: activeChat,
-        workspaceId,
-        createdBy: userId,
-        status: 'running',
-      }),
-    ).rejects.toThrow();
-
-    // findActiveByChat returns exactly the one active run.
-    const active = await runRepo.findActiveByChat(activeChat, workspaceId);
-    expect(active!.id).toBe(first.id);
-
-    // Once it settles, the slot frees and a new run may start.
-    await runRepo.update(first.id, workspaceId, {
-      status: 'succeeded',
-      finishedAt: new Date(),
-    });
-    expect(
-      await runRepo.findActiveByChat(activeChat, workspaceId),
-    ).toBeUndefined();
-    const second = await runRepo.insert({
-      chatId: activeChat,
-      workspaceId,
-      createdBy: userId,
-      status: 'running',
-    });
-    expect(second.id).not.toBe(first.id);
-    await runRepo.update(second.id, workspaceId, {
-      status: 'aborted',
-      finishedAt: new Date(),
-    });
-  });
-
-  it('DETACHED run: persists + finalizes succeeded with NO subscriber, reconnect returns state', async () => {
-    // A dedicated chat so the active-run slot is clean.
-    const runChat = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-
-    // beginRun = the runner starts the turn (registers an in-memory controller).
-    const handle = await service.beginRun({
-      chatId: runChat,
-      workspaceId,
-      userId,
-    });
-    expect(handle.signal.aborted).toBe(false);
-    expect(service.isLocallyActive(handle.runId)).toBe(true);
-
-    // The assistant projection row (#183) is seeded + linked.
-    const seeded = await messageRepo.insert({
-      chatId: runChat,
-      workspaceId,
-      userId,
-      role: 'assistant',
-      content: '',
-      status: 'streaming',
-      metadata: { parts: [] } as never,
-    });
-    await service.linkAssistantMessage(handle.runId, workspaceId, seeded.id);
-
-    // Progress is persisted as steps finish — NO HTTP socket involved here at all.
-    await service.recordStep(handle.runId, workspaceId, 1);
-    await messageRepo.update(seeded.id, workspaceId, {
-      content: 'partial work',
-      metadata: { parts: [{ type: 'text', text: 'partial work' }] },
-    });
-
-    // The turn completes; finalize the projection then the run.
-    await messageRepo.update(seeded.id, workspaceId, {
-      content: 'final answer',
-      status: 'completed',
-    });
-    await service.finalizeRun(handle.runId, workspaceId, 'completed');
-
-    expect(service.isLocallyActive(handle.runId)).toBe(false);
-
-    // Reconnect: the latest run for the chat + its projected message, from the DB.
-    const run = await service.getLatestForChat(runChat, workspaceId);
-    expect(run!.status).toBe('succeeded');
-    expect(run!.stepCount).toBe(1);
-    expect(run!.assistantMessageId).toBe(seeded.id);
-    expect(run!.finishedAt).toBeTruthy();
-    const message = await messageRepo.findById(seeded.id, workspaceId);
-    expect(message!.status).toBe('completed');
-    expect(message!.content).toBe('final answer');
-  });
-
-  it('EXPLICIT stop aborts the run signal, marks the row, and settles as aborted', async () => {
-    const runChat = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-    const handle = await service.beginRun({
-      chatId: runChat,
-      workspaceId,
-      userId,
-    });
-
-    // User presses Stop.
-    const stopped = await service.requestStop(handle.runId, workspaceId);
-    expect(stopped).toBe(true);
-    expect(handle.signal.aborted).toBe(true);
-
-    // The row carries the stop request (distinct from a disconnect, which would
-    // leave stop_requested_at NULL).
-    const afterStop = await runRepo.findById(handle.runId, workspaceId);
-    expect(afterStop!.stopRequestedAt).toBeTruthy();
-
-    // The terminal callback (onAbort) settles the run.
-    await service.finalizeRun(handle.runId, workspaceId, 'aborted');
-    const run = await service.getLatestForChat(runChat, workspaceId);
-    expect(run!.status).toBe('aborted');
-  });
-
-  it('markStopRequested is a no-op on an already-settled run (returns undefined)', async () => {
-    const runChat = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-    const run = await runRepo.insert({
-      chatId: runChat,
-      workspaceId,
-      createdBy: userId,
-      status: 'running',
-    });
-    await runRepo.update(run.id, workspaceId, {
-      status: 'succeeded',
-      finishedAt: new Date(),
-    });
-    const marked = await runRepo.markStopRequested(run.id, workspaceId);
-    expect(marked).toBeUndefined();
-  });
-
-  it('sweepRunning aborts STALE dangling runs but not fresh or settled ones', async () => {
-    const sweepChat1 = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-    const sweepChat2 = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-    const sweepChat3 = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-
-    const stale = await runRepo.insert({
-      chatId: sweepChat1,
-      workspaceId,
-      createdBy: userId,
-      status: 'running',
-    });
-    const fresh = await runRepo.insert({
-      chatId: sweepChat2,
-      workspaceId,
-      createdBy: userId,
-      status: 'running',
-    });
-    const settled = await runRepo.insert({
-      chatId: sweepChat3,
-      workspaceId,
-      createdBy: userId,
-      status: 'running',
-    });
-    await runRepo.update(settled.id, workspaceId, {
-      status: 'succeeded',
-      finishedAt: new Date(),
-    });
-    // Backdate the stale run's updatedAt past the 10-minute staleness window.
-    await db
-      .updateTable('aiChatRuns')
-      .set({ updatedAt: new Date(Date.now() - 20 * 60 * 1000) })
-      .where('id', '=', stale.id)
-      .execute();
-
-    // WINDOWED sweep (phase-2 multi-instance timer path): only runs older than the
-    // staleness window are aborted, so a sibling replica's fresh run survives. The
-    // no-arg boot sweep (variant C) is unconditional — covered separately below.
-    const swept = await runRepo.sweepRunning({ staleMs: SWEEP_RUN_STALE_MS });
-    expect(swept).toBeGreaterThanOrEqual(1);
-
-    expect((await runRepo.findById(stale.id, workspaceId))!.status).toBe(
-      'aborted',
-    );
-    // Fresh (recently-updated) running run survives the WINDOWED sweep — a sibling
-    // replica may still be executing it.
-    expect((await runRepo.findById(fresh.id, workspaceId))!.status).toBe(
-      'running',
-    );
-    expect((await runRepo.findById(settled.id, workspaceId))!.status).toBe(
-      'succeeded',
-    );
-
-    // cleanup active fresh run
-    await runRepo.update(fresh.id, workspaceId, {
-      status: 'aborted',
-      finishedAt: new Date(),
-    });
-  });
-
-  it('sweepRunning() with NO args (boot sweep / variant C) aborts even a FRESH running run', async () => {
-    // F1/DECISION C at the SQL level: the unconditional boot sweep has NO
-    // staleness window, so a run updated just now (a fast restart) is settled too
-    // — otherwise it would stay 'running' forever and 409 every future turn.
-    const bootChat = (
-      await createChat(db, { workspaceId, creatorId: userId })
-    ).id;
-    const fresh = await runRepo.insert({
-      chatId: bootChat,
-      workspaceId,
-      createdBy: userId,
-      status: 'running',
-    });
-    // updatedAt = now (fresh, untouched). The no-arg sweep settles it anyway.
-    const swept = await runRepo.sweepRunning();
-    expect(swept).toBeGreaterThanOrEqual(1);
-    expect((await runRepo.findById(fresh.id, workspaceId))!.status).toBe(
-      'aborted',
-    );
-  });
-});

packages/editor-ext/src/lib/comment/comment.ts

@@ -172,7 +172,28 @@ export const Comment = Mark.create<ICommentOptions, ICommentStorage>({
     const commentId = HTMLAttributes?.["data-comment-id"] || null;
     const resolved = HTMLAttributes?.["data-resolved"] || false;
 
-    if (typeof window === "undefined" || typeof document === "undefined") {
+    // The in-process MCP module injects a jsdom `global.document` into the Node
+    // server, so `typeof document === "undefined"` is not enough to detect SSR.
+    // On any Node runtime always return a plain, serializable spec array; the
+    // interactive live-DOM branch below is browser-only. This stops server-side
+    // HTML/Markdown export (happy-dom DOMSerializer) from appending a foreign
+    // jsdom node into a happy-dom tree.
+    // Safe in the browser: Vite substitutes only `process.env` (a member
+    // expression), NOT the bare `process` object, so `typeof process` is
+    // "undefined" in the client bundle → isNodeRuntime is false → the interactive
+    // live-DOM branch below still runs and comment marks stay clickable in the
+    // editor. This browser-safety is load-bearing and NOT covered by a test
+    // (client vitest runs under jsdom→node, where isNodeRuntime is true). Do NOT
+    // add a `process` polyfill (e.g. vite-plugin-node-polyfills) without
+    // revisiting this guard, or comment interactivity dies silently.
+    const isNodeRuntime =
+      typeof process !== "undefined" && !!process.versions?.node;
+
+    if (
+      typeof window === "undefined" ||
+      typeof document === "undefined" ||
+      isNodeRuntime
+    ) {
       return [
         "span",
         mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {

packages/editor-ext/src/lib/image/image.ts

@@ -449,7 +449,9 @@ export function applyAlignment(container: HTMLElement, align: string) {
     // the next line when the viewport is narrow. The right/bottom padding
     // provides the gap between images in a row and between wrapped rows;
     // vertical-align: top keeps rows of different-height images aligned by
-    // their top edge.
+    // their top edge. Horizontal centering of the whole row is handled by the
+    // client stylesheet (media.css) via a :has() rule on the parent block
+    // container, since the row has no wrapper element of its own.
     container.style.display = "inline-block";
     container.style.verticalAlign = "top";
     container.style.padding = "0 10px 10px 0";

packages/mcp/.gitignore

@@ -0,0 +1 @@
+node_modules/node_modules