fix(#234 review r3): close the transient-error flash the round-2 safety-net opened (F7/F8)

F7: the round-2 isError safety-net released the stopping latch too broadly. In
TanStack Query v5 (retry:false) the query's data is RETAINED on error, so
runQueryFailed can be true while `run` is still an ACTIVE held run — a single
transient GET-run failure between Stop and settle released the latch early and
re-opened the observer merge, flashing the growing detached run over the frozen row
(exactly the F4 flash the safety-net was meant not to reintroduce). Extract the
decision into a pure shouldClearLatchOnQueryError helper gated on !isRunActive(run)
(so it only ever cures the permanent-null-freeze, never releases against an active
run) and call it from the effect with `run` in deps. Document the latent invariant
that the null-branch clear is safe only because refetchInterval stops polling on
empty data.
F8: unit-test the real helper (not a mirror) — an active run + transient error does
NOT clear the latch (catches F7, non-vacuous against the pre-fix condition); null /
terminal run clears. The stale-terminal-run guarantee stays covered by
shouldClearStoppingLatch's tests.

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

.env.example

@@ -190,6 +190,20 @@ 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,10 +72,7 @@ git log -1 --format='Author: %an <%ae>%nCommitter: %cn <%ce>'
 
 ### 4. Push and PR to develop
 
-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
+PRs always target `develop`. 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):
@@ -97,24 +94,18 @@ git remote set-url gitea "$ORIG_URL"
 unset AGENT_PASS SAFE_PASS
 ```
 
-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:
+The PR is created via the Gitea REST API (Basic Auth as `claude_code`):
 
-- `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).
+```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"
+```
 
-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`.
+`base: develop`, `head: <branch>`. In the PR body: what was done, what is out
+of scope, verification results (tsc/lint/tests).
 
 > 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
@@ -161,25 +152,23 @@ below.
 | Agent user (Gitea/git) | `claude_code` |
 | Agent email | `claude_code@vvzvlad.xyz` |
 | Keychain password | `security find-generic-password -s gitea-claude-code -w` |
-| 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`. |
+| PR API | `https://gitea.vvzvlad.xyz/api/v1/repos/vvzvlad/gitmost/pulls` (here `gitmost` is the repo's real slug on the server) |
 | 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 MCP)
+## Creating issues (Gitea `tea` CLI)
 
-File issues through the **Gitea MCP** (server `gitea`), not a CLI — call
-`issue_write` with:
+Issues are filed with the official Gitea CLI `tea`, already logged in as
+`claude_code` (`tea logins list` shows the `gitea` login as default):
 
-- `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>]`.
+```bash
+tea issues create --repo vvzvlad/gitmost --labels feature \
+  --title '<title>' --description "$(cat body.md)"
+```
 
-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.
+> Gotcha (tea 0.14.1): the issue body flag is `--description`/`-d`, **not**
+> `--body` — passing `--body` fails with `flag provided but not defined: -body`.
 
 ---
 
@@ -278,6 +267,7 @@ 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,10 +14,8 @@ 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. 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
+  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
   losslessly through markdown as `data-align`, like the other alignment
   values.
 
@@ -72,6 +70,19 @@ 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
@@ -86,53 +97,6 @@ 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
 
@@ -198,25 +162,6 @@ 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** — 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.
+- ✅ **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.
 
 ### In progress
 
@@ -187,17 +187,14 @@ start the new migrations apply on top of your existing schema (`CREATE EXTENSION
 - Spaces
 - Permissions management
 - Groups
-- Comments (with resolve / re-open and hover tooltips showing the comment text)
+- Comments (with resolve / re-open)
 - 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); 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
+- AI agent chat over your wiki (read + write, RAG search, external MCP / web access)
 
 ### 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,18 +174,14 @@ dump/restore, существующий каталог данных переис
 - Пространства (Spaces)
 - Управление правами доступа
 - Группы
-- Комментарии (с резолвом / переоткрытием и всплывающими подсказками с текстом комментария при наведении)
+- Комментарии (с резолвом / переоткрытием)
 - История страниц
 - Поиск
 - Вложения файлов
 - Встраивания (Airtable, Loom, Miro и другие)
 - Переводы (10+ языков)
 - Встроенный MCP-сервер (`/mcp`)
-- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет); окно чата закрепляется в боковом меню, а агент узнаёт о ваших правках страницы между ходами
-- Кнопки код-блока оверлеем, селектор языка появляется при наведении
-- Кнопка «Ударение» (U+0301) в bubble-меню
-- Позиция чтения (прокрутка) восстанавливается после перезагрузки
-- Slash-меню терпимо к неправильной раскладке (ЙЦУКЕН↔QWERTY)
+- Чат с AI-агентом по вики (чтение + запись, RAG-поиск, внешние MCP / доступ в интернет)
 
 ### Скриншоты
 

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 «{{role}}» on behalf of {{person}}": "AI agent «{{role}}» on behalf of {{person}}",
-  "AI agent {{name}}": "AI agent {{name}}",
+  "AI-agent": "AI-agent",
+  "Edited by AI agent on behalf of {{name}}": "Edited by AI agent on behalf of {{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,8 +724,7 @@
   "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
   "Delete this chat?": "Удалить этот чат?",
   "Deleted successfully": "Успешно удалено",
-  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
-  "AI agent {{name}}": "AI-агент {{name}}",
+  "Edited by AI agent on behalf of {{name}}": "Отредактировано AI-агентом от имени {{name}}",
   "Failed to delete chat": "Не удалось удалить чат",
   "Failed to rename chat": "Не удалось переименовать чат",
   "Failed": "Ошибка",

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

@@ -14,22 +14,6 @@ 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";
@@ -68,9 +52,8 @@ export default function ExportModal({
       });
       onClose();
     } catch (err) {
-      const message = await extractExportError(err);
       notifications.show({
-        message: t("Export failed") + (message ? `: ${message}` : ""),
+        message: "Export failed:" + err.response?.data.message,
         color: "red",
       });
       console.error("export error", err);

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

@@ -12,7 +12,6 @@ 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";
@@ -54,13 +53,7 @@ export function AppHeader() {
               aria-label={t("Sidebar toggle")}
               opened={mobileOpened}
               onClick={toggleMobile}
-              // 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}
+              hiddenFrom="sm"
               size="sm"
             />
           </Tooltip>
@@ -70,7 +63,7 @@ export function AppHeader() {
               aria-label={t("Sidebar toggle")}
               opened={desktopOpened}
               onClick={toggleDesktop}
-              visibleFrom={NAVBAR_COLLAPSE_BREAKPOINT}
+              visibleFrom="sm"
               size="sm"
             />
           </Tooltip>

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

@@ -6,7 +6,6 @@ import SettingsSidebar from "@/components/settings/settings-sidebar.tsx";
 import { useAtom } from "jotai";
 import {
   APP_NAVBAR_ID,
-  NAVBAR_COLLAPSE_BREAKPOINT,
   asideStateAtom,
   desktopSidebarAtom,
   mobileSidebarAtom,
@@ -89,13 +88,7 @@ export default function GlobalAppShell({
       header={{ height: 45 }}
       navbar={{
         width: isSpaceRoute ? sidebarWidth : 300,
-        // `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,
+        breakpoint: "sm",
         collapsed: {
           mobile: !mobileOpened,
           desktop: !desktopOpened,
@@ -104,7 +97,7 @@ export default function GlobalAppShell({
       aside={
         isPageRoute && {
           width: 420,
-          breakpoint: "md",
+          breakpoint: "sm",
           collapsed: { mobile: !isAsideOpen, desktop: !isAsideOpen },
         }
       }

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

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

@@ -1,101 +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 { 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("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

@@ -1,183 +0,0 @@
-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;
-
-/**
- * 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;
-}
-
-/**
- * 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,
-}: 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 });
-
-  const stack = (
-    <Box
-      pos="relative"
-      style={{
-        width: GLYPH_SIZE,
-        height: GLYPH_SIZE,
-        flexShrink: 0,
-        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>
-      )}
-      <Box pos="relative" style={{ zIndex: 1 }}>
-        <AgentGlyph agent={agent} />
-      </Box>
-    </Box>
-  );
-
-  return (
-    <Group gap={6} wrap="nowrap" style={{ minWidth: 0 }}>
-      <Tooltip label={tooltip} withArrow>
-        {stack}
-      </Tooltip>
-      <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

@@ -0,0 +1,96 @@
+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

@@ -0,0 +1,99 @@
+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, useSetAtom } from "jotai";
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { useLocation, useMatch } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { useQueryClient } from "@tanstack/react-query";
@@ -41,13 +41,24 @@ 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 } from "@/features/ai-chat/services/ai-chat-service.ts";
+import {
+  exportAiChat,
+  stopRun,
+} from "@/features/ai-chat/services/ai-chat-service.ts";
 import { useChatSession } from "@/features/ai-chat/hooks/use-chat-session.ts";
 import {
   shouldCollapseOnOutsidePointer,
@@ -234,6 +245,147 @@ 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"
@@ -882,6 +1034,18 @@ 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,6 +11,7 @@ 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[];
@@ -30,6 +31,8 @@ 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,
     };
   },
 }));
@@ -140,3 +143,56 @@ 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,6 +24,7 @@ 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,
@@ -86,6 +87,29 @@ 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;
 }
 
 /**
@@ -131,6 +155,10 @@ export default function ChatThread({
   assistantName,
   onTurnFinished,
   onServerChatId,
+  observedRow,
+  onStreamingChange,
+  autonomousRunsEnabled,
+  onServerStop,
 }: ChatThreadProps) {
   const { t } = useTranslation();
 
@@ -216,6 +244,16 @@ 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.
@@ -274,7 +312,7 @@ export default function ChatThread({
     [],
   );
 
-  const { messages, sendMessage, status, stop, error } = useChat({
+  const { messages, sendMessage, status, stop, error, setMessages } = 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).
@@ -365,7 +403,14 @@ export default function ChatThread({
       return;
     lastForwardedChatIdRef.current = serverChatId;
     onServerChatId(serverChatId);
-  }, [messages, onServerChatId]);
+    // #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]);
 
   // Live "turn was interrupted" marker for the CURRENT session. The red error
   // banner (driven by `error`) covers the error case; this covers an aborted
@@ -378,6 +423,27 @@ 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
@@ -409,6 +475,40 @@ 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
@@ -420,6 +520,11 @@ 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]);
 
@@ -539,7 +644,7 @@ export default function ChatThread({
         <ChatInput
           onSend={(text) => sendMessage({ text })}
           onQueue={enqueue}
-          onStop={stop}
+          onStop={handleStop}
           isStreaming={isStreaming}
         />
       </Stack>

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

@@ -12,6 +12,7 @@ import {
   deleteAiChat,
   deleteAiRole,
   getAiChatMessages,
+  getAiChatRun,
   getAiChats,
   getAiRoleCatalog,
   getAiRoleCatalogBundle,
@@ -24,6 +25,7 @@ import {
 import {
   IAiChat,
   IAiChatMessageRow,
+  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -34,6 +36,7 @@ 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"];
@@ -51,16 +54,18 @@ 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>(() => {
@@ -90,7 +95,9 @@ 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,
   });
 
@@ -131,6 +138,34 @@ 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();
@@ -280,11 +315,14 @@ 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

@@ -0,0 +1,92 @@
+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,6 +5,7 @@ import {
   IAiChatListParams,
   IAiChatMessageRow,
   IAiChatMessagesParams,
+  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -42,6 +43,38 @@ 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,6 +200,38 @@ 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

@@ -0,0 +1,303 @@
+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

@@ -0,0 +1,151 @@
+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,7 +23,6 @@ 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();
@@ -123,11 +122,6 @@ 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,30 +40,20 @@ function renderItem(comment: IComment) {
   );
 }
 
-describe("CommentListItem — agent avatar stack", () => {
-  it('renders the agent avatar stack when createdSource === "agent"', () => {
-    // External-MCP shape: agent is the account itself, no launcher behind.
-    renderItem(
-      baseComment({
-        createdSource: "agent",
-        aiChatId: null,
-        agent: { name: "Service Bot", avatarUrl: null },
-        launcher: null,
-      }),
-    );
-    // The stack renders the agent name label (the creator name is also shown in
-    // the row header, so it appears more than once).
-    expect(screen.getAllByText("Service Bot").length).toBeGreaterThan(0);
-  });
-
-  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();
+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();
     expect(screen.getByText("Service Bot")).toBeDefined();
   });
 
-  // 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).
+  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).
 });

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

@@ -1,5 +1,5 @@
 import { Group, Text, Box } from "@mantine/core";
-import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
+import { AiAgentBadge } from "@/components/ui/ai-agent-badge.tsx";
 import React, { useEffect, useRef, useState } from "react";
 import classes from "./comment.module.css";
 import { useAtom, useAtomValue } from "jotai";
@@ -132,10 +132,9 @@ function CommentListItem({
                 {comment.creator.name}
               </Text>
 
-              {comment.createdSource === "agent" && comment.agent && (
-                <AgentAvatarStack
-                  agent={comment.agent}
-                  launcher={comment.launcher}
+              {comment.createdSource === "agent" && (
+                <AiAgentBadge
+                  authorName={comment.creator?.name}
                   aiChatId={comment.aiChatId}
                 />
               )}

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

@@ -1,9 +1,5 @@
 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;
@@ -28,11 +24,6 @@ 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

@@ -1,231 +0,0 @@
-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

@@ -1,193 +0,0 @@
-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 { CustomTypography } from "./custom-typography";
+import { Typography } from "@tiptap/extension-typography";
 import { TextStyle } from "@tiptap/extension-text-style";
 import { Color } from "@tiptap/extension-color";
 import { Youtube } from "@tiptap/extension-youtube";
@@ -245,9 +245,7 @@ export const mainExtensions = [
       return ReactMarkViewRenderer(SpoilerView);
     },
   }),
-  // 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,
+  Typography,
   TrailingNode,
   GlobalDragHandle.configure({
     customNodes: ["transclusionSource", "transclusionReference", "pageEmbed"],

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

@@ -1,9 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { htmlToMarkdown } from "@docmost/editor-ext";
-import {
-  normalizeTableColumnWidths,
-  classifyClipboardSelection,
-} from "./markdown-clipboard";
+import { normalizeTableColumnWidths } from "./markdown-clipboard";
 
 // normalizeTableColumnWidths mutates a DOM subtree (jsdom provides document).
 function root(html: string): HTMLElement {
@@ -128,171 +124,3 @@ 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,36 +27,24 @@ export const MarkdownClipboard = Extension.create({
         key: new PluginKey("markdownClipboard"),
         props: {
           clipboardTextSerializer: (slice) => {
-            const topLevelNodes: { name: string; childCount: number }[] = [];
+            const listTypes = ["bulletList", "orderedList", "taskList"];
+            let topLevelCount = 0;
+            let hasList = false;
             slice.content.forEach((node) => {
-              topLevelNodes.push({
-                name: node.type.name,
-                childCount: node.childCount,
-              });
+              if (listTypes.includes(node.type.name)) {
+                hasList = true;
+                topLevelCount += node.childCount;
+              } else {
+                topLevelCount++;
+              }
             });
 
-            const { asMarkdown, wrapBareRows } =
-              classifyClipboardSelection(topLevelNodes);
-            if (!asMarkdown) return null;
+            if (!hasList || topLevelCount < 2) return null;
 
             const div = document.createElement("div");
             const serializer = DOMSerializer.fromSchema(this.editor.schema);
             const fragment = serializer.serializeFragment(slice.content);
-
-            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);
-            }
+            div.appendChild(fragment);
             return htmlToMarkdown(div.innerHTML);
           },
           handlePaste: (view, event, slice) => {
@@ -165,55 +153,6 @@ 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) is idempotent: re-asserting the same target does not scroll again", () => {
+  it("(a3) restores at most once per mount even if called again", () => {
     vi.useFakeTimers();
     window.sessionStorage.setItem(`${KEY_PREFIX}once`, "500");
     setScrollHeight(2000); // tall enough to restore synchronously
@@ -111,12 +111,8 @@ 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: the redundancy guard sees
-    // the window is already at the target and does nothing.
+    // restoreScrollPosition]) must NOT scroll again and yank the reader.
     act(() => {
       result.current.restoreScrollPosition();
     });
@@ -166,84 +162,6 @@ 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"));
@@ -303,55 +221,6 @@ 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,5 +1,4 @@
-import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
-import type { Editor } from "@tiptap/react";
+import { useCallback, useEffect, useRef } from "react";
 
 // Throttle interval for persisting the scroll position while the user reads.
 const SAVE_THROTTLE_MS = 250;
@@ -14,18 +13,6 @@ 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}`;
 }
@@ -61,41 +48,32 @@ 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 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.
+ * 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.
  */
 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. 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.
+  // 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.
   //
   // 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);
-  // Set once the reader shows unambiguous scroll intent; restore must never yank
-  // a reader who has already started scrolling.
-  const userInteractedRef = useRef(false);
+  // Guards so restore runs at most once per page mount.
+  const hasRestoredRef = 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.
@@ -136,43 +114,14 @@ 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;
@@ -188,8 +137,9 @@ export function useScrollPosition(pageId: string): {
   }, [pageId]);
 
   const restoreScrollPosition = useCallback(() => {
-    // The reader took over — never yank them back.
-    if (userInteractedRef.current) return;
+    // Run at most once per page mount.
+    if (hasRestoredRef.current) return;
+    hasRestoredRef.current = true;
 
     // Anchor priority: a `#hash` in the URL is handled by useEditorScroll.
     if (window.location.hash) return;
@@ -198,26 +148,9 @@ export function useScrollPosition(pageId: string): {
     // Nothing meaningful to restore to.
     if (targetY <= 0) return;
 
-    // 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 start = Date.now();
 
     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;
@@ -225,12 +158,10 @@ 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) {
-        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" });
-        }
+        window.scrollTo({
+          top: Math.min(targetY, Math.max(maxScroll, 0)),
+          behavior: "auto",
+        });
         pollTimerRef.current = null;
         return;
       }
@@ -244,37 +175,3 @@ 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

@@ -1,141 +0,0 @@
-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 { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
+import { useScrollPosition } 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,6 +143,7 @@ export default function PageEditor({
     [isComponentMounted],
   );
   const { handleScrollTo } = useEditorScroll({ canScroll });
+  const { restoreScrollPosition } = useScrollPosition(pageId);
   // Providers only created once per pageId
   const providersRef = useRef<{
     local: IndexeddbPersistence;
@@ -481,10 +482,10 @@ export default function PageEditor({
     }
   }, [yjsConnectionStatus, isSynced]);
 
-  // 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);
+  // Restore the saved reading position once the live content is laid out.
+  useEffect(() => {
+    if (!showStatic && editor) restoreScrollPosition();
+  }, [showStatic, editor, restoreScrollPosition]);
 
   return (
     <TransclusionLookupProvider>

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

@@ -71,22 +71,3 @@
   }
 }
 
-/* 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 { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
+import { AiAgentBadge } from "@/components/ui/ai-agent-badge.tsx";
 import { formattedDate } from "@/lib/time";
 import classes from "./css/history.module.css";
 import clsx from "clsx";
@@ -99,13 +99,12 @@ const HistoryItem = memo(function HistoryItem({
           </>
         )}
 
-        {isAgentEdit && historyItem.agent && (
-          <AgentAvatarStack
-            agent={historyItem.agent}
-            launcher={historyItem.launcher}
+        {isAgentEdit && (
+          <AiAgentBadge
+            authorName={historyItem.lastUpdatedBy?.name}
             aiChatId={historyItem.lastUpdatedAiChatId}
-            // The history row owns the modal: close it when the stack deep-links
-            // into the chat (the stack no longer reaches into page-history).
+            // The history row owns the modal: close it when the badge deep-links
+            // into the chat (the badge no longer reaches into page-history).
             onActivate={() => setHistoryModalOpen(false)}
           />
         )}

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

@@ -1,8 +1,3 @@
-import type {
-  AgentInfo,
-  LauncherInfo,
-} from "@/components/ui/agent-avatar-stack.tsx";
-
 interface IPageHistoryUser {
   id: string;
   name: string;
@@ -29,9 +24,4 @@ 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,30 +13,20 @@ 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>(
-    `${OPEN_TREE_NODES_KEY_PREFIX}${scopeKey}`,
-    {},
-    openTreeNodesStorage,
-    { getOnInit: true },
-  ),
+  atomWithStorage<OpenMap>(`openTreeNodes:${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).
-// 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 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

@@ -1,265 +0,0 @@
-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,206 +1,8 @@
 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";
 
-// 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);
-  },
-);
+export const treeDataAtom = atom<SpaceTreeNode[]>([]);
 
 // Atom
 export const appendNodeChildrenAtom = atom(

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

@@ -1,222 +0,0 @@
-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,8 +71,7 @@ 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. `scopeKeyAtom` is also
-// re-exported (the real module exports it for the persisted tree-data atom).
+// unchanged while staying inside the test store.
 vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
   const { atom } = await import("jotai");
   type OpenMap = Record<string, boolean>;
@@ -87,17 +86,11 @@ vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
       set(base, next);
     },
   );
-  // 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 };
+  return { openTreeNodesAtom };
 });
 
 import SpaceTree, { SpaceTreeApi } from "./space-tree";
-import {
-  treeDataAtom,
-  flushPendingTreeDataWrites,
-} from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { treeDataAtom } 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";
@@ -141,10 +134,6 @@ 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,7 +30,6 @@ 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";
@@ -200,81 +199,45 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
   const openIdsRef = useRef(openIds);
   openIdsRef.current = openIds;
 
-  // 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
+  // Reconnect refresh (#159 #8): on a socket reconnect, re-fetch and reconcile
+  // the children of every currently-open, already-loaded branch of THIS space,
   // 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.
-  // No first-connect guard is needed: space-tree usually mounts AFTER the
-  // initial connect, so every `connect` it sees is a reconnect; the rare
+  // 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
   // initial-connect case has an empty tree, so the refresh is a harmless no-op.
   useEffect(() => {
     if (!socket) return;
-    const onConnect = () => {
-      refreshOpenBranches();
+    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);
+        }
+      }
     };
     socket.on("connect", onConnect);
     return () => {
       socket.off("connect", onConnect);
     };
-  }, [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]);
+  }, [socket, setData]);
 
   const handleToggle = useCallback(
     async (id: string, isOpen: boolean) => {
@@ -370,17 +333,12 @@ 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>
       )}
-      {/* 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 && (
+      {isDataLoaded && filteredData.length > 0 && (
         <DocTree<SpaceTreeNode>
           data={filteredData}
           openIds={openIds}

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

@@ -8,7 +8,6 @@ import {
   closeIds,
   mergeRootTrees,
   loadedOpenBranchIds,
-  pruneCollapsedChildren,
   sortPositionKeys,
   pageToTreeNode,
 } from "./utils";
@@ -439,62 +438,3 @@ 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,41 +293,6 @@ 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,6 +394,10 @@ 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);
@@ -403,6 +407,8 @@ 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);
@@ -730,6 +736,37 @@ 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 (
@@ -960,6 +997,31 @@ 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,6 +26,9 @@ 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;
@@ -65,6 +68,9 @@ 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,7 +1,6 @@
 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",
@@ -72,12 +71,6 @@ 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

@@ -0,0 +1,527 @@
+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

@@ -0,0 +1,452 @@
+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,6 +19,7 @@ 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,6 +53,7 @@ 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

@@ -0,0 +1,163 @@
+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,6 +1,7 @@
 import {
   BadRequestException,
   Body,
+  ConflictException,
   Controller,
   ForbiddenException,
   HttpCode,
@@ -20,14 +21,25 @@ 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, User, Workspace } from '@docmost/db/types/entity.types';
+import {
+  AiChat,
+  AiChatMessage,
+  AiChatRun,
+  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 { AiChatService, AiChatStreamBody } from './ai-chat.service';
+import {
+  AiChatRunHooks,
+  AiChatService,
+  AiChatStreamBody,
+} from './ai-chat.service';
+import { AiChatRunService } from './ai-chat-run.service';
 import { AiTranscriptionService } from './ai-transcription.service';
 import {
   BoundChatDto,
@@ -35,7 +47,9 @@ 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';
@@ -52,6 +66,7 @@ export class AiChatController {
 
   constructor(
     private readonly aiChatService: AiChatService,
+    private readonly aiChatRunService: AiChatRunService,
     private readonly aiChatRepo: AiChatRepo,
     private readonly aiChatMessageRepo: AiChatMessageRepo,
     private readonly aiTranscription: AiTranscriptionService,
@@ -137,6 +152,75 @@ 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')
@@ -188,11 +272,20 @@ 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 } };
+    const settings = (workspace.settings ?? {}) as {
+      ai?: { chat?: boolean; autonomousRuns?: 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
@@ -216,6 +309,58 @@ 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;
@@ -230,18 +375,44 @@ 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 before aborting the agent loop.
+      // so log it here.
       if (!res.raw.writableEnded) {
-        this.logger.warn(
-          `AI chat stream: client disconnected before completion; aborting turn ` +
-            `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
-        );
-        controller.abort();
+        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();
+        }
       }
     };
     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();
@@ -256,15 +427,32 @@ 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 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);
+      // 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);
+      }
       if (!res.raw.headersSent) {
-        res.raw.statusCode = 500;
+        const status = isHttp ? err.getStatus() : 500;
+        const payload = isHttp
+          ? err.getResponse()
+          : { error: 'Internal server error' };
+        res.raw.statusCode = status;
         res.raw.setHeader('Content-Type', 'application/json');
-        res.raw.end(JSON.stringify({ error: 'Internal server error' }));
+        res.raw.end(
+          JSON.stringify(
+            typeof payload === 'string' ? { message: payload } : payload,
+          ),
+        );
       } else if (!res.raw.writableEnded) {
         res.raw.end();
       }

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

@@ -57,6 +57,7 @@ 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,6 +3,7 @@ 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';
@@ -42,6 +43,7 @@ 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,11 +303,6 @@ 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,17 +85,11 @@ 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 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.';
+  '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.';
 
 /**
  * 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,5 +1,7 @@
 import { Logger } from '@nestjs/common';
-import { AiChatService } from './ai-chat.service';
+import { AiChatService, AiChatRunHooks } from './ai-chat.service';
+import { AiChatRunService } from './ai-chat-run.service';
+import type { User, Workspace } from '@docmost/db/types/entity.types';
 
 /**
  * Lifecycle unit tests for AiChatService.onModuleInit (#183 crash-recovery
@@ -60,3 +62,98 @@ 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

@@ -0,0 +1,486 @@
+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,32 +356,6 @@ 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);
-  });
 });
 
 /**
@@ -398,6 +372,12 @@ 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,168 +269,6 @@ 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,7 +15,6 @@
  */
 
 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';
@@ -64,7 +63,6 @@ const LABELS: Record<
     tools: Record<string, string>;
     ranTool: (name: string) => string;
     stillGenerating: string;
-    pageEditedByUser: string;
   }
 > = {
   en: {
@@ -85,8 +83,6 @@ 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: 'Без названия',
@@ -106,29 +102,9 @@ 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';
@@ -232,23 +208,6 @@ 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
@@ -307,26 +266,6 @@ 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,6 +43,30 @@ 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

@@ -1,237 +0,0 @@
-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,27 +207,17 @@ export class CommentService {
       false,
     );
 
-    // 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,
-    });
+    comment.content = commentContent;
+    comment.editedAt = editedAt;
+    comment.updatedAt = editedAt;
 
     this.wsService.emitCommentEvent(comment.spaceId, comment.pageId, {
       operation: 'commentUpdated',
       pageId: comment.pageId,
-      comment: updatedComment,
+      comment,
     });
 
-    return updatedComment;
+    return comment;
   }
 
   async resolveComment(

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

@@ -55,6 +55,14 @@ 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,6 +526,20 @@ 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) {
@@ -579,6 +593,7 @@ 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,6 +31,7 @@ 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';
@@ -105,6 +106,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     TemplateRepo,
     AiChatRepo,
     AiChatMessageRepo,
+    AiChatRunRepo,
     AiChatPageSnapshotRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,
@@ -139,6 +141,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     TemplateRepo,
     AiChatRepo,
     AiChatMessageRepo,
+    AiChatRunRepo,
     AiChatPageSnapshotRepo,
     AiProviderCredentialsRepo,
     AiMcpServerRepo,

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

@@ -0,0 +1,106 @@
+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

@@ -1,129 +0,0 @@
-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

@@ -1,93 +0,0 @@
-/**
- * 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,6 +121,23 @@ 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

@@ -0,0 +1,82 @@
+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

@@ -0,0 +1,212 @@
+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

@@ -1,124 +0,0 @@
-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,24 +12,6 @@ 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 {
@@ -40,30 +22,13 @@ export class CommentRepo {
     commentId: string,
     opts?: { includeCreator: boolean; includeResolvedBy: boolean },
   ): Promise<Comment> {
-    const comment = await this.db
+    return 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) {
@@ -72,18 +37,15 @@ export class CommentRepo {
       .selectAll('comments')
       .select((eb) => this.withCreator(eb))
       .select((eb) => this.withResolvedBy(eb))
-      .select((eb) => this.withAgentRole(eb))
       .where('pageId', '=', pageId);
 
-    const result = await executeWithCursorPagination(query, {
+    return 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(
@@ -120,12 +82,6 @@ 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
@@ -160,30 +116,3 @@ 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

@@ -1,107 +0,0 @@
-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,25 +12,6 @@ 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 {
@@ -113,18 +94,15 @@ export class PageHistoryRepo {
       .select(this.baseFields)
       .select((eb) => this.withLastUpdatedBy(eb))
       .select((eb) => this.withContributors(eb))
-      .select((eb) => this.withAgentRole(eb))
       .where('pageId', '=', pageId);
 
-    const result = await executeWithCursorPagination(query, {
+    return 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(
@@ -160,12 +138,6 @@ 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
@@ -179,30 +151,3 @@ 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,6 +644,35 @@ 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
@@ -680,6 +709,7 @@ 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,6 +3,7 @@ import {
   AiAgentRoles,
   AiChats,
   AiChatMessages,
+  AiChatRuns,
   AiChatPageSnapshots,
   Attachments,
   Comments,
@@ -56,10 +57,12 @@ 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'
->;
+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>;
 
 // 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
@@ -214,11 +217,14 @@ 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'>
 >;
@@ -288,7 +294,9 @@ 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

@@ -1,82 +0,0 @@
-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

@@ -0,0 +1,304 @@
+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,28 +172,7 @@ export const Comment = Mark.create<ICommentOptions, ICommentStorage>({
     const commentId = HTMLAttributes?.["data-comment-id"] || null;
     const resolved = HTMLAttributes?.["data-resolved"] || false;
 
-    // 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
-    ) {
+    if (typeof window === "undefined" || typeof document === "undefined") {
       return [
         "span",
         mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {

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

@@ -449,9 +449,7 @@ 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. 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.
+    // their top edge.
     container.style.display = "inline-block";
     container.style.verticalAlign = "top";
     container.style.padding = "0 10px 10px 0";

packages/mcp/.gitignore

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