test(#248 F3): make empty-over-empty test actually reach the store empty-guard

The "does not block an empty store over an already-empty page" test set the
stored page.content to TiptapTransformer.fromYdoc(document,'default') — exactly
the value tiptapJson is computed from — so isDeepStrictEqual(tiptapJson,
page.content) was TRUE and onStoreDocument RETURNED at the unchanged short-circuit
before ever reaching the empty-guard. It exercised the old short-circuit, not the
new guard's `!isEmptyParagraphDoc(page.content)` branch (the only NEW branch
protecting empty existing pages from over-blocking); the condition could be
removed and the test would still pass (false coverage).

Set stored content to an empty paragraph with `content: []` — empty per
isEmptyParagraphDoc but NOT deep-equal to the live doc (which normalizes to a
paragraph with `attrs: { indent: 0 }` and no content key). Execution now skips
the short-circuit and enters the guard; reorient the assertion to "the write is
NOT blocked" (updatePage IS called). Verified the test now FAILS if the
`!isEmptyParagraphDoc(page.content)` condition is removed.

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

.env.example

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

AGENTS.md

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

CHANGELOG.md

@@ -58,19 +58,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   append/prepend fragments, nor to COMMENT bodies — a comment may legitimately
   contain a standalone footnote definition, which canonicalization would drop.
   (#228)
-- **Detached, autonomous agent runs that survive a browser disconnect.** When the
-  new `settings.ai.autonomousRuns` workspace flag is on (off by default), an
-  AI-chat turn becomes a first-class, server-side RUN tracked in a new
-  `ai_chat_runs` table instead of a socket-bound stream: closing the tab or
-  losing the connection no longer aborts the turn — it keeps executing and
-  persisting server-side, and only an explicit Stop ends it. A client can
-  reconnect and live-follow (or stop) an in-flight run via `POST /ai-chat/run`
-  (resolve the latest run + its assistant message for a chat) and
-  `POST /ai-chat/stop` (stop by `runId` or `chatId`). A partial unique index
-  enforces one active run per chat, and a startup sweep settles any run left
-  dangling by a restart. Phase 1 is single-instance-only (cross-instance Stop is
-  not yet reliable); the server warns at startup on a horizontally-scaled
-  deployment. (#184)
 
 ### Changed
 

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

@@ -17,7 +17,7 @@ import {
   IconPlus,
   IconX,
 } from "@tabler/icons-react";
-import { useAtom, useAtomValue, useSetAtom } from "jotai";
+import { useAtom, useSetAtom } from "jotai";
 import { useMatch } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { useQueryClient } from "@tanstack/react-query";
@@ -34,12 +34,9 @@ import {
   AI_CHATS_RQ_KEY,
   AI_CHAT_MESSAGES_RQ_KEY,
   useAiChatMessagesQuery,
-  useAiChatRunQuery,
   useAiChatsQuery,
   useAiRolesQuery,
 } from "@/features/ai-chat/queries/ai-chat-query.ts";
-import { 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";
@@ -165,61 +162,6 @@ export default function AiChatWindow() {
   const { data: messageRows, isLoading: messagesLoading } =
     useAiChatMessagesQuery(activeChatId ?? undefined);
 
-  // #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
-  // this workspace. The reconnect endpoint itself is NOT flag-gated server-side
-  // (it is only owner-gated and returns `{ run: null }` when the chat has no
-  // run); but when the feature is off no runs are ever created, so polling it
-  // would always come back empty — we gate it off here to avoid pointless polls.
-  const workspace = useAtomValue(workspaceAtom);
-  const autonomousRunsEnabled =
-    workspace?.settings?.ai?.autonomousRuns === true;
-
-  // Whether THIS tab is the one actively streaming the open chat's run locally
-  // (it started the run here and holds the SSE). Reported up from ChatThread. We
-  // are the STREAMER while true and a passive OBSERVER while false — the basis of
-  // the observer-vs-streamer detection. Reset to false by the fresh ChatThread's
-  // mount effect on every chat switch.
-  const [localStreaming, setLocalStreaming] = useState(false);
-  const onStreamingChange = useCallback((streaming: boolean) => {
-    setLocalStreaming(streaming);
-  }, []);
-
-  // 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 } = useAiChatRunQuery(
-    activeChatId ?? undefined,
-    autonomousRunsEnabled && !localStreaming,
-  );
-  const run = runData?.run ?? null;
-  // 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)
-    ? (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;
-    }
-    if (finalizedRunIdRef.current === run.id) return;
-    finalizedRunIdRef.current = run.id;
-    queryClient.invalidateQueries({
-      queryKey: AI_CHAT_MESSAGES_RQ_KEY(activeChatId),
-    });
-  }, [run, activeChatId, queryClient]);
-
   // 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"
@@ -694,12 +636,6 @@ export default function AiChatWindow() {
               assistantName={currentRole?.name}
               onTurnFinished={onTurnFinished}
               onServerChatId={onServerChatId}
-              // #184: live-follow a still-running run when we reopened the chat as
-              // a passive observer; null when there is nothing to observe or this
-              // tab is the streamer. onStreamingChange lets the window stop polling
-              // while we are the streamer.
-              observedRow={observedRow}
-              onStreamingChange={onStreamingChange}
             />
           )}
         </div>

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

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

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

@@ -24,7 +24,6 @@ import {
 } from "@/features/ai-chat/utils/role-launch.ts";
 import { describeChatError } from "@/features/ai-chat/utils/error-message.ts";
 import { extractServerChatId } from "@/features/ai-chat/utils/adopt-chat-id.ts";
-import { mergeObservedMessage } from "@/features/ai-chat/utils/run-polling.ts";
 import {
   dequeue,
   enqueueMessage,
@@ -87,19 +86,6 @@ interface ChatThreadProps {
    *  Copy/export button available mid-stream). Distinct from onTurnFinished,
    *  which fires only at the terminal outcome. */
   onServerChatId?: (serverChatId?: string) => void;
-  /** #184 reconnect-and-live-follow. When THIS tab reopened a chat whose agent
-   *  run is still going (it is a PASSIVE OBSERVER — it did not start the run here),
-   *  the parent polls the reconnect endpoint and feeds the run's incrementally-
-   *  persisted assistant message here; we merge it into the live list so new
-   *  steps/tool-calls appear as they are persisted. Null when there is nothing to
-   *  observe (no run, feature off, or this tab IS the streamer). The merge is
-   *  ADDITIONALLY guarded by our own `isStreaming`, so a stale value can never
-   *  fight the local stream when we are the streamer. */
-  observedRow?: IAiChatMessageRow | null;
-  /** Report this tab's live streaming status up to the parent, so it can stop
-   *  polling the run while WE are the active streamer (the SSE owns the view) and
-   *  resume once we go idle. Called from an effect on every transition. */
-  onStreamingChange?: (streaming: boolean) => void;
 }
 
 /**
@@ -145,8 +131,6 @@ export default function ChatThread({
   assistantName,
   onTurnFinished,
   onServerChatId,
-  observedRow,
-  onStreamingChange,
 }: ChatThreadProps) {
   const { t } = useTranslation();
 
@@ -290,7 +274,7 @@ export default function ChatThread({
     [],
   );
 
-  const { messages, sendMessage, status, stop, error, setMessages } = useChat({
+  const { messages, sendMessage, status, stop, error } = useChat({
     // Stable per-mount key. Existing chats use their real id; new chats use a
     // generated client id (never `undefined`) so the store is NOT re-created on
     // every render mid-stream (see `chatStoreId` above).
@@ -394,27 +378,6 @@ export default function ChatThread({
 
   const isStreaming = status === "submitted" || status === "streaming";
 
-  // #184: report our live streaming status up so the parent stops polling the run
-  // while WE are the streamer (the SSE owns the view) and resumes once we go idle.
-  // Effect (not render) so it never updates parent state during our own render;
-  // fires on mount with `false`, which also re-syncs the parent after a chat
-  // switch remounts this thread (a fresh mount is idle until the user sends).
-  useEffect(() => {
-    onStreamingChange?.(isStreaming);
-  }, [isStreaming, onStreamingChange]);
-
-  // #184 passive-observer merge: when the parent feeds a polled run message (we
-  // reopened a chat whose run is still going and did NOT start it here), merge it
-  // into the live list so new steps/tool-calls appear as they are persisted. Hard-
-  // gated by `!isStreaming`: if THIS tab is actually the streamer, the local SSE
-  // owns the view and a stale observedRow must never overwrite it. `observedRow`
-  // is a stable per-poll object, so this runs once per poll, not per render.
-  useEffect(() => {
-    if (isStreaming || !observedRow) return;
-    const observed = rowToUiMessage(observedRow);
-    setMessages((prev) => mergeObservedMessage(prev, observed));
-  }, [observedRow, isStreaming, setMessages]);
-
   // "Send now" on a queued message: interrupt the current turn and immediately
   // send THIS message, keeping the agent's partial output. Other queued messages
   // stay queued and flush normally after the new turn. Reuses the existing

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

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

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

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

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

@@ -5,7 +5,6 @@ import {
   IAiChatListParams,
   IAiChatMessageRow,
   IAiChatMessagesParams,
-  IAiChatRunResponse,
   IAiRole,
   IAiRoleCatalog,
   IAiRoleCatalogBundle,
@@ -43,23 +42,6 @@ export async function getAiChatMessages(
   return req.data;
 }
 
-/**
- * Reconnect to the latest agent run of a chat (#184). Returns the run's
- * persisted lifecycle state and the assistant message it materializes (the
- * partial output while the run is in-flight, the final output once it finished).
- * The DB is the source of truth, so this works for an in-flight run (the browser
- * dropped, the run kept going) and a finished one alike; `{ run: null }` when the
- * chat has never had a run. Owner-gated server-side (the requesting user must own
- * the chat); it is NOT flag-gated — when the feature is off the chat simply has no
- * runs, so the endpoint returns `{ run: null }`.
- */
-export async function getAiChatRun(
-  chatId: string,
-): Promise<IAiChatRunResponse> {
-  const req = await api.post<IAiChatRunResponse>("/ai-chat/run", { chatId });
-  return req.data;
-}
-
 /**
  * Resolve the chat bound to a document (the current user's most-recent chat
  * created on that page), or null when there is none. Drives auto-open-on-page.

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

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

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

@@ -1,104 +0,0 @@
-import { describe, it, expect } from "vitest";
-import type { UIMessage } from "@ai-sdk/react";
-import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
-import {
-  RUN_POLL_INTERVAL_MS,
-  isRunActive,
-  runPollInterval,
-  shouldObserveRun,
-  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("mergeObservedMessage", () => {
-  it("replaces the message with the same id in place (per-step growth)", () => {
-    const prev = [makeMsg("u1", "hi"), makeMsg("a1", "step 1")];
-    const observed = makeMsg("a1", "step 1\nstep 2");
-    const next = mergeObservedMessage(prev, observed);
-    expect(next).toHaveLength(2);
-    expect(next[1]).toBe(observed);
-    expect(next[0]).toBe(prev[0]); // untouched
-    expect(next).not.toBe(prev); // new array (never mutates input)
-  });
-
-  it("appends when the observed message is not yet present", () => {
-    const prev = [makeMsg("u1", "hi")];
-    const observed = makeMsg("a1", "first token");
-    const next = mergeObservedMessage(prev, observed);
-    expect(next).toHaveLength(2);
-    expect(next[1]).toBe(observed);
-  });
-
-  it("returns the original list unchanged when there is nothing to merge", () => {
-    const prev = [makeMsg("u1", "hi")];
-    expect(mergeObservedMessage(prev, null)).toBe(prev);
-    expect(mergeObservedMessage(prev, undefined)).toBe(prev);
-  });
-});

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

@@ -1,71 +0,0 @@
-import type { UIMessage } from "@ai-sdk/react";
-import type { IAiChatRun } from "@/features/ai-chat/types/ai-chat.types.ts";
-
-/**
- * Reconnect-and-live-follow helpers (#184). When a chat is reopened while its
- * agent run is STILL going, this tab is a PASSIVE OBSERVER: it did not start the
- * run here (no local SSE stream), so it catches up by POLLING the reconnect
- * endpoint (`POST /ai-chat/run`) and merging the run's incrementally-persisted
- * assistant message into the rendered thread. These are the small pure decisions
- * that machinery hangs off, extracted so they can be unit-tested in isolation
- * (mirrors how reindex polling / editor-sync-state are tested).
- */
-
-/** How often to re-poll the reconnect endpoint while a run is ACTIVE. */
-export const RUN_POLL_INTERVAL_MS = 2000;
-
-// 'pending' and 'running' are the two ACTIVE statuses; 'succeeded' | 'failed' |
-// 'aborted' are TERMINAL (and any unknown future status is treated as terminal,
-// so a stale/odd value never polls forever).
-const ACTIVE_STATUSES = new Set(["pending", "running"]);
-
-/** Whether a run is still going (worth polling / merging live updates from). */
-export function isRunActive(run: IAiChatRun | null | undefined): boolean {
-  return !!run && ACTIVE_STATUSES.has(run.status);
-}
-
-/**
- * The TanStack Query `refetchInterval` value for the run query: poll every
- * {@link RUN_POLL_INTERVAL_MS} while the run is active, and `false` (stop) once
- * it is terminal or there is no run. Polling is thus naturally bounded by the run
- * reaching a terminal status — no separate timeout cap is needed.
- */
-export function runPollInterval(
-  run: IAiChatRun | null | undefined,
-): number | false {
-  return isRunActive(run) ? RUN_POLL_INTERVAL_MS : false;
-}
-
-/**
- * Observer-vs-streamer decision. We render the polled run message (catch up +
- * keep advancing) ONLY when this tab is a passive observer: there IS a run AND
- * this tab is NOT the one locally streaming it (we reconnected, we didn't start
- * it here). When this tab is the streamer, the live SSE stream owns the view, so
- * we neither poll nor merge — avoiding a double-render fight. Terminal runs still
- * merge (so the final persisted output is shown on reopen); the poll itself is
- * stopped separately by {@link runPollInterval}.
- */
-export function shouldObserveRun(
-  run: IAiChatRun | null | undefined,
-  localStreaming: boolean,
-): boolean {
-  return !!run && !localStreaming;
-}
-
-/**
- * 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/workspace/types/workspace.types.ts

@@ -65,9 +65,6 @@ export interface IWorkspaceAiSettings {
   dictation?: boolean;
   dictationStreaming?: boolean;
   publicShareAssistant?: boolean;
-  // #184: detached agent runs (a run survives a browser disconnect and can be
-  // reconnected to / live-followed on reopen). Gates the run-reconnect polling.
-  autonomousRuns?: boolean;
 }
 
 export interface IWorkspaceSharingSettings {

apps/server/src/collaboration/extensions/persistence-store.spec.ts

@@ -205,31 +205,61 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(historyQueue.add).toHaveBeenCalledTimes(1);
   });
 
-  // #206 persist-6 — RED (it.failing): a momentarily-empty live Y.Doc must not
-  // overwrite non-empty persisted content. `onStoreDocument` empty-guards the
-  // LOAD path but not the STORE path, so today an empty doc (a client/agent
-  // glitch, a bad merge, an emptying transclusion) is written straight over the
-  // page and the content is wiped silently. A store-side empty-guard is a real
-  // behaviour change (a deliberate "select-all + delete" is also empty), so it
-  // is left UNFIXED pending a product decision; this documents the data-loss
-  // path and flips to a normal passing test the moment the guard lands.
-  it.failing(
-    'does NOT overwrite non-empty content with a momentarily-empty live doc (persist-6)',
-    async () => {
-      const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
-      const document = ydocFor(emptyDoc);
-      pageRepo.findById.mockResolvedValue({
-        ...persistedHumanPage('IGNORED'),
-        content: doc('IMPORTANT RICH CONTENT'),
-      });
+  // #206 persist-6 — FIXED: a momentarily-empty live Y.Doc must not overwrite
+  // non-empty persisted content. `onStoreDocument` empty-guarded the LOAD path
+  // but not the STORE path, so an empty doc (a client/agent glitch, a bad
+  // merge, an emptying transclusion) was written straight over the page and the
+  // content was wiped silently. The store-side empty-guard now skips the write
+  // when the incoming doc is empty and the stored page is non-empty. A real
+  // intentional-clear UX is tracked separately in issue #251.
+  it('does NOT overwrite non-empty content with a momentarily-empty live doc (persist-6)', async () => {
+    const emptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    const document = ydocFor(emptyDoc);
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: doc('IMPORTANT RICH CONTENT'),
+    });
 
-      await ext.onStoreDocument(buildData(document, 'user') as any);
+    await ext.onStoreDocument(buildData(document, 'user') as any);
 
-      // Desired contract: the empty incoming doc is rejected and the rich page
-      // survives. Today updatePage is called with the empty content (data loss).
-      expect(pageRepo.updatePage).not.toHaveBeenCalled();
-    },
-  );
+    // The empty incoming doc is rejected and the rich page survives.
+    expect(pageRepo.updatePage).not.toHaveBeenCalled();
+    // No false-success side effects for a write that never happened.
+    expect((document as any).broadcastStateless).not.toHaveBeenCalled();
+    expect(historyQueue.add).not.toHaveBeenCalled();
+  });
+
+  // persist-6 — a legitimately-empty existing page must still be writable when
+  // the empty live doc actually DIFFERS from the stored content (so the
+  // unchanged short-circuit does NOT fire and execution reaches the empty-guard).
+  // This exercises the guard's third condition `!isEmptyParagraphDoc(page.content)`:
+  // because the stored page is ALSO empty, the guard must NOT block the write.
+  // The live doc normalizes to a paragraph carrying `attrs: { indent: 0 }` and no
+  // `content` key; the stored page is an empty paragraph with `content: []` —
+  // both empty per `isEmptyParagraphDoc`, but NOT `isDeepStrictEqual`, so the
+  // store passes the short-circuit (~line 208) and genuinely enters the guard
+  // (~line 229). If the `!isEmptyParagraphDoc(page.content)` condition were
+  // removed, the guard would block this write and updatePage would never run,
+  // failing this test.
+  it('does not block an empty store over an already-empty page (persist-6)', async () => {
+    const liveEmptyDoc = { type: 'doc', content: [{ type: 'paragraph' }] };
+    const document = ydocFor(liveEmptyDoc);
+    // Stored content is empty per isEmptyParagraphDoc (paragraph with content:[])
+    // but structurally NOT deep-equal to the normalized live doc — so execution
+    // skips the unchanged short-circuit and reaches the empty-guard.
+    const storedEmptyDoc = { type: 'doc', content: [{ type: 'paragraph', content: [] }] };
+    pageRepo.findById.mockResolvedValue({
+      ...persistedHumanPage('IGNORED'),
+      content: storedEmptyDoc,
+    });
+
+    await ext.onStoreDocument(buildData(document, 'user') as any);
+
+    // Empty-over-empty reaches the guard, which must let the write through
+    // (the stored page is empty, so the empty-overwrite protection does not
+    // apply). updatePage IS called — proving `!isEmptyParagraphDoc(page.content)`.
+    expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+  });
 
   // persist-1 — when every attempt fails the hook must NOT report a phantom
   // success: no "page.updated" badge broadcast and no history snapshot for

apps/server/src/collaboration/extensions/persistence.extension.ts

@@ -210,6 +210,35 @@ export class PersistenceExtension implements Extension {
             return;
           }
 
+          // #206 persist-6 — store-side empty-guard. A momentarily-empty live
+          // Y.Doc (a client/agent glitch, a bad merge, a transclusion that
+          // emptied) must NOT overwrite non-empty persisted content. The LOAD
+          // path already guards emptiness (onLoadDocument only hydrates from db
+          // when the live doc isEmpty); the STORE path did not, so an empty
+          // serialization was written straight over the page, wiping it
+          // silently. Skip the write when the incoming doc is an empty
+          // paragraph doc AND the stored page is non-empty. New/empty pages are
+          // unaffected (stored content is already empty), and an unchanged doc
+          // was already short-circuited above.
+          //
+          // This unconditionally blocks empty-over-non-empty: a deliberate
+          // select-all + delete is currently indistinguishable from a glitch at
+          // this layer, so data-loss prevention wins. A real intentional-clear
+          // UX (a distinct signal threaded from the client) is tracked in issue
+          // #251; do not re-add an escape hatch here without that signal.
+          if (
+            isEmptyParagraphDoc(tiptapJson as any) &&
+            page.content &&
+            !isEmptyParagraphDoc(page.content as any)
+          ) {
+            this.logger.warn(
+              `Skipping store for ${pageId}: empty live doc would overwrite ` +
+                `non-empty persisted content`,
+            );
+            page = null;
+            return;
+          }
+
           let contributorIds = undefined;
           try {
             const existingContributors = page.contributorIds || [];

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

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

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

@@ -1,426 +0,0 @@
-import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
-import { AiChatRunRepo } from '@docmost/db/repos/ai-chat/ai-chat-run.repo';
-import { AiChatRun } from '@docmost/db/types/entity.types';
-import { isUniqueViolation, violatedConstraint } from '@docmost/db/utils';
-import { EnvironmentService } from '../../integrations/environment/environment.service';
-
-/** Name of the partial unique index enforcing "one active run per chat" (see the
- *  ai_chat_runs migration). A 23505 on THIS constraint is the race-safe signal
- *  that a concurrent turn already owns the chat — distinct from any other unique
- *  collision, which must NOT be silently treated as "already active". */
-export const ONE_ACTIVE_RUN_PER_CHAT_INDEX = 'ai_chat_runs_one_active_per_chat';
-
-/**
- * Thrown by {@link AiChatRunService.beginRun} when the run-row INSERT loses the
- * race for a chat's single active slot (the partial unique index rejects it with
- * a 23505). This is the AUTHORITATIVE concurrency gate: the controller's cheap
- * pre-check is only a fast-path, and a request that slips past it must NOT run
- * untracked. The caller (AiChatService.stream) translates this into a 409 and
- * aborts the turn BEFORE any AI/provider call.
- */
-export class RunAlreadyActiveError extends Error {
-  constructor(public readonly chatId: string) {
-    super(`An agent run is already in progress for chat ${chatId}`);
-    this.name = 'RunAlreadyActiveError';
-  }
-}
-
-/**
- * The terminal status of a TURN (the #183 assistant-row lifecycle) maps onto the
- * terminal status of a RUN (#184). A turn that completed -> the run succeeded; a
- * turn that errored -> the run failed; a turn aborted (explicit user stop) -> the
- * run aborted. Pure + unit-testable.
- */
-export type TurnTerminalStatus = 'completed' | 'error' | 'aborted';
-export type RunTerminalStatus = 'succeeded' | 'failed' | 'aborted';
-
-export function mapTurnStatusToRun(
-  status: TurnTerminalStatus,
-): RunTerminalStatus {
-  switch (status) {
-    case 'completed':
-      return 'succeeded';
-    case 'error':
-      return 'failed';
-    case 'aborted':
-      return 'aborted';
-  }
-}
-
-/** An in-flight run held in process memory: its AbortController is the ONLY thing
- *  that can stop the turn (an explicit user stop), independent of the browser
- *  socket. A mere disconnect never touches it, so the run keeps going. */
-interface ActiveRun {
-  controller: AbortController;
-  chatId: string;
-  workspaceId: string;
-}
-
-/** The live handle the streaming path drives a run through (returned by
- *  {@link AiChatRunService.beginRun}). The `signal` governs the agent loop's
- *  abort — wired to the run, NOT to the HTTP socket. */
-export interface RunHandle {
-  runId: string;
-  signal: AbortSignal;
-}
-
-/**
- * AiChatRunService (#184 phase 1) — owns the agent RUN as a first-class,
- * server-side lifecycle object detached from the HTTP request / browser window.
- *
- * Responsibilities:
- *  - create a run row when a turn starts (pending -> running) 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. Records `stop_requested_at` on the row (only while active) and
-   * aborts the in-process controller if this replica owns the run. 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 marked = await this.runRepo.markStopRequested(runId, workspaceId);
-    const entry = this.active.get(runId);
-    if (entry) {
-      // Abort the live turn -> streamText onAbort fires -> the partial is
-      // persisted (#183) and finalizeRun settles the row as 'aborted'.
-      entry.controller.abort();
-    }
-    return Boolean(marked) || Boolean(entry);
-  }
-
-  /** Latest persisted run for a chat — the reconnect target (an in-flight or
-   *  finished run). Pure read-through to the repo. */
-  getLatestForChat(
-    chatId: string,
-    workspaceId: string,
-  ): Promise<AiChatRun | undefined> {
-    return this.runRepo.findLatestByChat(chatId, workspaceId);
-  }
-
-  /** Fetch a run by id (workspace-scoped). Used to resolve + ownership-check an
-   *  explicit stop targeting a runId. */
-  getRun(runId: string, workspaceId: string): Promise<AiChatRun | undefined> {
-    return this.runRepo.findById(runId, workspaceId);
-  }
-
-  /** The active run on a chat, if any (used to reject a concurrent start with a
-   *  clean 409 before committing to the stream). */
-  getActiveForChat(
-    chatId: string,
-    workspaceId: string,
-  ): Promise<AiChatRun | undefined> {
-    return this.runRepo.findActiveByChat(chatId, workspaceId);
-  }
-
-  /** Test/diagnostic seam: whether this replica is holding a live controller for
-   *  the run. */
-  isLocallyActive(runId: string): boolean {
-    return this.active.has(runId);
-  }
-}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,337 +0,0 @@
-import { ConflictException, Logger } from '@nestjs/common';
-
-// Mock the AI SDK so we can PROVE no provider call is made for the turn we are
-// about to reject. The race rejection happens at runHooks.begin(), long before
-// any streamText/generateText, so these never resolve a real model.
-jest.mock('ai', () => ({
-  streamText: jest.fn(),
-  generateText: jest.fn(),
-  convertToModelMessages: jest.fn(() => []),
-  stepCountIs: jest.fn(() => () => false),
-}));
-
-import { streamText, generateText } from 'ai';
-import { AiChatService } from './ai-chat.service';
-import { RunAlreadyActiveError } from './ai-chat-run.service';
-
-/**
- * Race-closure coverage for the "one active run per chat" guard (#184).
- *
- * THE BUG: two simultaneous POST /ai-chat/stream on the same chat both pass the
- * controller's cheap pre-check (TOCTOU), so the loser's run-row INSERT hits the
- * partial unique index. Previously that 23505 was SWALLOWED and the second turn
- * streamed UNTRACKED (no runId, not stoppable). THE FIX: beginRun surfaces a
- * RunAlreadyActiveError and stream() turns it into a 409 BEFORE any AI call —
- * the second turn never runs.
- */
-describe('AiChatService.stream — concurrent-run race rejection (#184)', () => {
-  const streamTextMock = streamText as unknown as jest.Mock;
-  const generateTextMock = generateText as unknown as jest.Mock;
-
-  beforeEach(() => {
-    streamTextMock.mockReset();
-    generateTextMock.mockReset();
-  });
-
-  // Minimal service whose only reachable deps before begin() are aiChatRepo
-  // (resolve the existing chat) — everything past begin must remain untouched.
-  function makeService(beginImpl: () => Promise<unknown>) {
-    const aiChatMessageRepo = { insert: jest.fn() };
-    const aiChatRepo = {
-      // An existing chat: stream keeps the supplied chatId and skips creation.
-      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
-      insert: jest.fn(),
-    };
-    const svc = new AiChatService(
-      {} as never, // ai
-      aiChatRepo as never,
-      aiChatMessageRepo as never,
-      {} as never, // 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,
-      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'),
-    );
-  });
-});

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

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

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

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

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

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

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

@@ -1,104 +0,0 @@
-import { type Kysely, sql } from 'kysely';
-
-/**
- * `ai_chat_runs` — the agent RUN as a first-class, server-side lifecycle object
- * (#184 phase 1: autonomous agent runs detached from the browser window).
- *
- * Until now an agent turn lived ONLY as long as the HTTP request was open
- * (`res.hijack()` in ai-chat.controller.ts); a browser disconnect aborted it.
- * This table makes a turn a persistent object the server owns: it is created
- * when a run starts, transitions pending -> running -> succeeded|failed|aborted,
- * and survives the subscriber (browser) going away. 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/ai-chat/ai-chat-message.repo.ts

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

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

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

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

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

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

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

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

@@ -3,7 +3,6 @@ import {
   AiAgentRoles,
   AiChats,
   AiChatMessages,
-  AiChatRuns,
   Attachments,
   Comments,
   Groups,
@@ -56,12 +55,10 @@ export type UpdatableAiChat = Updateable<Omit<AiChats, 'id'>>;
 // full-text search. It is omitted from the public type so it never leaks
 // into HTTP responses or the chat history fed to the language model.
 export type AiChatMessage = Omit<Selectable<AiChatMessages>, 'tsv'>;
-export type InsertableAiChatMessage = Omit<Insertable<AiChatMessages>, 'tsv'>;
-
-// AI Chat Run (#184 phase 1): the agent run as a first-class lifecycle object,
-// detached from the HTTP request / browser window.
-export type AiChatRun = Selectable<AiChatRuns>;
-export type InsertableAiChatRun = Insertable<AiChatRuns>;
+export type InsertableAiChatMessage = Omit<
+  Insertable<AiChatMessages>,
+  'tsv'
+>;
 
 // AI Provider Credentials
 // SECURITY (D9/§8.1): holds encrypted per-workspace provider API keys.
@@ -207,14 +204,11 @@ export type UpdatableFavorite = Updateable<Omit<Favorites, 'id'>>;
 // Page Transclusion
 export type PageTransclusion = Selectable<PageTransclusions>;
 export type InsertablePageTransclusion = Insertable<PageTransclusions>;
-export type UpdatablePageTransclusion = Updateable<
-  Omit<PageTransclusions, 'id'>
->;
+export type UpdatablePageTransclusion = Updateable<Omit<PageTransclusions, 'id'>>;
 
 // Page Transclusion Reference
 export type PageTransclusionReference = Selectable<PageTransclusionReferences>;
-export type InsertablePageTransclusionReference =
-  Insertable<PageTransclusionReferences>;
+export type InsertablePageTransclusionReference = Insertable<PageTransclusionReferences>;
 export type UpdatablePageTransclusionReference = Updateable<
   Omit<PageTransclusionReferences, 'id'>
 >;
@@ -284,9 +278,7 @@ export type UpdatablePagePermission = Updateable<Omit<_PagePermissions, 'id'>>;
 // Page Verification
 export type PageVerification = Selectable<_PageVerifications>;
 export type InsertablePageVerification = Insertable<_PageVerifications>;
-export type UpdatablePageVerification = Updateable<
-  Omit<_PageVerifications, 'id'>
->;
+export type UpdatablePageVerification = Updateable<Omit<_PageVerifications, 'id'>>;
 
 // Page Verifier
 export type PageVerifier = Selectable<_PageVerifiers>;

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

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

packages/editor-ext/src/lib/markdown/utils/turndown.dataloss.test.ts

@@ -1,77 +1,147 @@
 import { describe, it, expect } from "vitest";
 import { htmlToMarkdown } from "./turndown.utils";
+import { markdownToHtml } from "./marked.utils";
 
 /**
- * #206 mdrt-2 — Markdown export must never SILENTLY drop a block.
+ * #206 mdrt-2 — Markdown export must never SILENTLY drop a block. (FIXED)
  *
- * `htmlToMarkdown` (turndown) only registers rules for a fixed set of custom
- * nodes (callout, taskItem, details, math, iframe, htmlEmbed, image, video,
- * footnote). Any other custom node — `transclusionReference`, `pageBreak`,
- * `mention`, `status` — falls through to turndown's default handling: an empty
- * wrapper is "blank" and removed, so the block disappears from the exported
- * Markdown with no trace. The invariant "never silently lose a block" is broken.
+ * `htmlToMarkdown` (turndown) historically only registered rules for a fixed
+ * set of custom nodes (callout, taskItem, details, math, iframe, htmlEmbed,
+ * image, video, footnote). Any other custom node — `transclusionReference`,
+ * `pageBreak`, `mention`, `status` — fell through to turndown's default
+ * handling: an empty wrapper is "blank" and removed, so the block disappeared
+ * from the exported Markdown with no trace, and `mention`/`status` collapsed to
+ * bare text, losing their identity (data-id / data-color). The invariant
+ * "never silently lose a block" was broken.
  *
- * The `it.fails` cases assert the DESIRED contract (the block survives export in
- * SOME form) and are RED today: they document the unfixed data loss and flip to
- * green the moment a turndown rule (real syntax or a lossless HTML-comment
- * placeholder) is added. A normal characterization `it` pins the exact current
- * lossy output so the regression is unambiguous.
+ * The fix adds lossless turndown rules that re-emit each of these nodes as raw
+ * HTML carrying every `data-*` attribute. Plain-Markdown viewers ignore the
+ * inert tag; the import path round-trips it (`markdownToHtml` passes the raw
+ * HTML through and each node's `parseHTML` rebuilds the ProseMirror node). These
+ * tests assert the surviving contract (the block is preserved AND its identity
+ * round-trips back through import).
  */
-describe("htmlToMarkdown — custom nodes without a turndown rule (#206 mdrt-2)", () => {
-  const wrap = (inner: string) =>
-    `<p>before</p>${inner}<p>after</p>`;
+describe("htmlToMarkdown — custom nodes are preserved losslessly (#206 mdrt-2)", () => {
+  const wrap = (inner: string) => `<p>before</p>${inner}<p>after</p>`;
 
-  it("CURRENTLY drops a pageBreak entirely (data loss)", () => {
+  it("preserves a pageBreak block on Markdown export", () => {
     const md = htmlToMarkdown(
       wrap('<div data-type="pageBreak" class="page-break"></div>'),
     );
-    // The page break vanishes: only the two paragraphs remain, nothing between.
     expect(md).toContain("before");
     expect(md).toContain("after");
-    expect(md).not.toMatch(/page-?break/i);
-    expect(md).not.toContain("---"); // not even a horizontal-rule fallback
+    // The break survives as an inert raw-HTML tag, not silently dropped.
+    expect(md).toMatch(/data-type="pageBreak"/);
+    expect(md).toMatch(/page-?break/i);
   });
 
-  it("CURRENTLY drops a transclusionReference entirely (data loss)", () => {
+  it("preserves a transclusionReference's identity on Markdown export", () => {
     const md = htmlToMarkdown(
       wrap('<div data-type="transclusionReference" data-id="abc"></div>'),
     );
     expect(md).toContain("before");
     expect(md).toContain("after");
-    // The data-id (the only thing that gives the reference identity) is gone.
-    expect(md).not.toContain("abc");
+    // The data-id (the only thing that gives the reference identity) survives.
+    expect(md).toContain("abc");
+    expect(md).toMatch(/data-type="transclusionReference"/);
   });
 
-  it.fails(
-    "should NOT lose a pageBreak block on Markdown export",
-    () => {
+  it("preserves a mention's data-id (stable identity) on Markdown export", () => {
+    const md = htmlToMarkdown(
+      '<p>hi <span data-type="mention" data-id="u1" data-label="Bob">@Bob</span> there</p>',
+    );
+    // The mention keeps its stable identity (data-id), not just the text.
+    expect(md).toContain("u1");
+    expect(md).toContain("Bob");
+    expect(md).toMatch(/data-type="mention"/);
+  });
+
+  it("preserves a status chip's color on Markdown export", () => {
+    const md = htmlToMarkdown(
+      '<p>s <span data-type="status" data-color="green">Done</span></p>',
+    );
+    // The chip's color (its identity) survives, not just the visible text.
+    expect(md).toContain("green");
+    expect(md).toContain("Done");
+    expect(md).toMatch(/data-type="status"/);
+  });
+
+  // The export form is only lossless if the import path can rebuild it. These
+  // assert the full MD -> HTML round-trip restores the node + its attributes,
+  // which is the marker <-> node contract each `parseHTML` relies on.
+  describe("import round-trip (markdownToHtml restores the node)", () => {
+    it("round-trips a pageBreak through export + import", async () => {
       const md = htmlToMarkdown(
         wrap('<div data-type="pageBreak" class="page-break"></div>'),
       );
-      // Desired: the break survives in some form (e.g. a `---` rule or marker).
-      expect(md).toMatch(/(-{3,}|page-?break)/i);
-    },
-  );
+      const html = await markdownToHtml(md);
+      expect(html).toMatch(/<div[^>]*data-type="pageBreak"[^>]*>/);
+      expect(html).toContain("before");
+      expect(html).toContain("after");
+    });
 
-  it.fails(
-    "should NOT lose a transclusionReference's identity on Markdown export",
-    () => {
+    it("round-trips a transclusionReference (keeps data-id)", async () => {
       const md = htmlToMarkdown(
         wrap('<div data-type="transclusionReference" data-id="abc"></div>'),
       );
-      // Desired: the referenced id survives so the block can be rebuilt.
-      expect(md).toContain("abc");
-    },
-  );
+      const html = await markdownToHtml(md);
+      expect(html).toMatch(/<div[^>]*data-type="transclusionReference"[^>]*>/);
+      expect(html).toContain("abc");
+    });
 
-  it.fails(
-    "should NOT lose a mention's data-id on Markdown export",
-    () => {
+    it("round-trips a mention (keeps data-id + data-label)", async () => {
       const md = htmlToMarkdown(
         '<p>hi <span data-type="mention" data-id="u1" data-label="Bob">@Bob</span> there</p>',
       );
-      // Desired: the mention keeps its stable identity (data-id), not just text.
-      expect(md).toContain("u1");
-    },
-  );
+      const html = await markdownToHtml(md);
+      expect(html).toMatch(/<span[^>]*data-type="mention"[^>]*>/);
+      expect(html).toContain("u1");
+      expect(html).toContain("Bob");
+    });
+
+    it("round-trips a status chip (keeps data-color)", async () => {
+      const md = htmlToMarkdown(
+        '<p>s <span data-type="status" data-color="green">Done</span></p>',
+      );
+      const html = await markdownToHtml(md);
+      expect(html).toMatch(/<span[^>]*data-type="status"[^>]*>/);
+      expect(html).toContain("green");
+    });
+
+    // HTML special chars in an attribute value or in a node's text must be
+    // ESCAPED when re-emitted as raw HTML, otherwise the exported tag is
+    // malformed and `markdownToHtml`'s parser cannot restore the original value
+    // (the same silent data loss this PR fixes). Dropping `<`/`>` escaping is the
+    // dangerous regression: a stray `<` or `>` corrupts the tag (or injects new
+    // markup), so the test data carries ALL of `&`, `"`, `<`, `>` in BOTH the
+    // data-label attribute and the visible text. That fully exercises
+    // escapeHtmlAttr's `&,",<,>` branches and escapeHtmlText's `&,<,>` branches
+    // (escapeHtmlText leaves `"` literal); the alphanumeric-only cases above hit
+    // none of them.
+    it("escapes HTML special chars (& \" < >) in attrs + text and round-trips them", async () => {
+      const md = htmlToMarkdown(
+        `<p>hi <span data-type="mention" data-id="u1" data-label="A &amp; &lt;B&gt; &quot;C&quot;">@A &amp; &lt;B&gt; "C"</span> there</p>`,
+      );
+
+      // (a) The exported Markdown carries a WELL-FORMED, correctly-escaped tag:
+      // the attribute escapes `&`, `<`, `>` AND `"`; the text escapes `&`, `<`,
+      // `>` (a `"` inside text content is legal, so it stays literal).
+      expect(md).toContain('data-label="A &amp; &lt;B&gt; &quot;C&quot;"');
+      expect(md).toContain('>@A &amp; &lt;B&gt; "C"</span>');
+      // And explicitly NOT the raw, tag-corrupting forms: a literal `<B>` (would
+      // mean `<`/`>` escaping was dropped in either the attr or the text)...
+      expect(md).not.toContain("<B>");
+      // ...nor the malformed attribute that an unescaped `"` would produce.
+      expect(md).not.toContain('data-label="A &amp; &lt;B&gt; "C""');
+
+      // (b) Import restores the ORIGINAL (unescaped) values, attribute and text.
+      const html = await markdownToHtml(md);
+      const dom = new DOMParser().parseFromString(html as string, "text/html");
+      const span = dom.querySelector('span[data-type="mention"]');
+      expect(span).not.toBeNull();
+      expect(span!.getAttribute("data-id")).toBe("u1");
+      expect(span!.getAttribute("data-label")).toBe('A & <B> "C"');
+      expect(span!.textContent).toBe('@A & <B> "C"');
+    });
+  });
 });

packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts

@@ -43,6 +43,54 @@ function fillEmptyFootnoteRefs(html: string): string {
   );
 }
 
+/**
+ * `pageBreak` and `transclusionReference` are childless atom <div>s. Like an
+ * empty footnote ref (see above), turndown treats a childless block as "blank"
+ * and replaces it with the blankRule BEFORE any custom rule can fire — so the
+ * node disappears from the export with no trace (#206 mdrt-2). Inject a
+ * zero-width space so the node is non-blank and our lossless rule runs; the
+ * rule rebuilds the tag from the element's attributes, so the injected char
+ * never reaches the output.
+ */
+function fillEmptyAtomBlocks(html: string): string {
+  return html.replace(
+    /<div\b([^>]*\bdata-type="(?:pageBreak|transclusionReference)"[^>]*)>\s*<\/div>/gi,
+    (_m, attrs) => `<div${attrs}>​</div>`,
+  );
+}
+
+/** HTML-escape an attribute value so a re-emitted raw-HTML tag is well-formed. */
+function escapeHtmlAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/** HTML-escape text placed inside a re-emitted raw-HTML element. */
+function escapeHtmlText(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Serialize ALL of an element's attributes back to a raw-HTML attribute string
+ * (leading space included). Generic on purpose: a custom node's identity lives
+ * entirely in its `data-*` attributes (data-id, data-color, data-source-page-id,
+ * data-transclusion-id, …), and serializing every attribute keeps the export
+ * lossless regardless of which attributes a given node carries.
+ */
+function serializeAttrs(node: any): string {
+  const attrs = node?.attributes;
+  if (!attrs) return '';
+  return Array.from(attrs as ArrayLike<{ name: string; value: string }>)
+    .map((attr) => ` ${attr.name}="${escapeHtmlAttr(attr.value ?? '')}"`)
+    .join('');
+}
+
 export function htmlToMarkdown(html: string): string {
   const turndownService = new TurndownService({
     headingStyle: 'atx',
@@ -69,12 +117,83 @@ export function htmlToMarkdown(html: string): string {
     video,
     footnoteReference,
     footnotesList,
+    pageBreak,
+    transclusionReference,
+    mention,
+    status,
   ]);
   return turndownService
-    .turndown(fillEmptyFootnoteRefs(html))
+    .turndown(fillEmptyAtomBlocks(fillEmptyFootnoteRefs(html)))
     .replaceAll('<br>', ' ');
 }
 
+/**
+ * Lossless export rules for custom nodes that have NO native Markdown syntax
+ * (#206 mdrt-2). Markdown cannot represent a page break, a transclusion
+ * reference, a mention's stable id, or a status chip's color — so rather than
+ * letting turndown silently drop them, each rule re-emits the node as raw HTML
+ * carrying every `data-*` attribute. Plain-Markdown viewers ignore the inert
+ * tag, and the import path round-trips it: `markdownToHtml` passes raw HTML
+ * through and each node's `parseHTML` (`div[data-type="…"]`, `span[…]`) rebuilds
+ * the ProseMirror node with its attributes intact.
+ */
+function pageBreak(turndownService: _TurndownService) {
+  turndownService.addRule('pageBreak', {
+    filter: function (node: HTMLInputElement) {
+      return (
+        node.nodeName === 'DIV' &&
+        node.getAttribute('data-type') === 'pageBreak'
+      );
+    },
+    replacement: function (_content: string, node: HTMLInputElement) {
+      return `\n\n<div${serializeAttrs(node)}></div>\n\n`;
+    },
+  });
+}
+
+function transclusionReference(turndownService: _TurndownService) {
+  turndownService.addRule('transclusionReference', {
+    filter: function (node: HTMLInputElement) {
+      return (
+        node.nodeName === 'DIV' &&
+        node.getAttribute('data-type') === 'transclusionReference'
+      );
+    },
+    replacement: function (_content: string, node: HTMLInputElement) {
+      return `\n\n<div${serializeAttrs(node)}></div>\n\n`;
+    },
+  });
+}
+
+function mention(turndownService: _TurndownService) {
+  turndownService.addRule('mention', {
+    filter: function (node: HTMLInputElement) {
+      return (
+        node.nodeName === 'SPAN' &&
+        node.getAttribute('data-type') === 'mention'
+      );
+    },
+    replacement: function (_content: string, node: HTMLInputElement) {
+      const text = escapeHtmlText(node.textContent || '');
+      return `<span${serializeAttrs(node)}>${text}</span>`;
+    },
+  });
+}
+
+function status(turndownService: _TurndownService) {
+  turndownService.addRule('status', {
+    filter: function (node: HTMLInputElement) {
+      return (
+        node.nodeName === 'SPAN' && node.getAttribute('data-type') === 'status'
+      );
+    },
+    replacement: function (_content: string, node: HTMLInputElement) {
+      const text = escapeHtmlText(node.textContent || '');
+      return `<span${serializeAttrs(node)}>${text}</span>`;
+    },
+  });
+}
+
 /**
  * Serialize the `htmlEmbed` node to Markdown.
  *