fix(ai-chat): ре-ревью #518 — CI-фиделити delta, attach-дубль, чистки (#491)

Ребейз на обновлённый feat/490 (PR #510, Option-A): стек #491 перенесён с
6e872f2d на 6e42752a; run-fsm.ts/chat-thread.tsx приехали из develop-версии
(W1/S4: RUN_ALREADY_ACTIVE несёт activeRunId + supersede-CAS адопция) — мои
#491-правки легли сверху без конфликтов, W1 НЕ откачен (run-fsm.ts == develop
байт-в-байт; RUN_ALREADY_ACTIVE диспатчит activeRunId).

1. [CI-fidelity] Дельта-курсор спек падал в CI unit-лейне: `.spec.ts` дефолтил
   на НЕмигрированный docmost → 5/6 ERROR relation does not exist (skip-гард ловит
   только connection-fail). Переименован в `*.int-spec.ts` (исключается из unit-
   regex `.spec.ts$`, гоняется в test:int, чей global-setup мигрирует docmost_test)
   + DSN по умолчанию → docmost_test. Теперь 6/6 реально исполняются в CI-верном
   окружении; overlap-мутация роняет RACE-тесты (не вакуумен).

2. [regression #137/#161] attach: отсутствие `n` схлопывалось в frontier 0 →
   finished-неротированный ран (coverageFloor 0) отдавал ВЕСЬ tail вместо 204;
   парамслесс/легаси-вкладка допишет полный replay → дубль. Различаем ОТСУТСТВИЕ
   `n` (null — не tail-aware) от `n=0` (tail-aware): контроллер шлёт null при
   missing/invalid; registry.attach(n: number|null) 204-ит finished-ран при
   n===null (старый `finished && !expectLive` гейт), n=0 по-прежнему отдаёт хвост.
   Тесты (registry + controller) + mutation-verify: нейтрализация гейта роняет их.

4. [conventions] Ring-кап env-var переименован RUN_STREAM_MAX_BUFFER_BYTES →
   AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES (префикс как у сиблингов) + запись в
   .env.example (дефолт 4MB, 0/invalid→дефолт, subscriber-cap=2×).

5. [docs] run-fsm.spec.md: item4 переписан («реализовано в #491 — дельта несёт
   run:{id,status}|null; клиент run-поле ещё не потребляет») + добавлена строка
   перехода POLL_IDLE_CAP stopping→idle (Review #4, редьюсер это делает).

6. [simplification] Удалена мёртвая цепочка reconstructRunParts /
   reconstructPartsFromRow (ноль прод-вызовов) + опц. messageRepo-инъекция в
   AiChatRunService + спек-блоки; вернётся с первым реальным вызывателем. Маркер
   metadata.stepsPersisted (реально используемый) сохранён.

DROP-пункты ревьюера (осиротевший import, DELTA_POLL_MAX_ROWS) не трогаю.
Прогон: server tsc 0, ai-chat unit 202, delta-int 6/6 (int-lane), int attach 6/6,
client vitest 403, tsc client 0 ai-chat, mcp 834/0. FSM-инварианты #488 сохранены.

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

.env.example

@@ -302,6 +302,16 @@ MCP_DOCMOST_PASSWORD=
 # enabled for a workspace, and the same single-instance constraint applies (the
 # registry is process-local).
 # AI_CHAT_RESUMABLE_STREAM=false
+#
+# Per-run replay ring cap (#491), in BYTES, for the resumable-stream registry
+# above. The registry buffers the run's recent SSE tail so a reopened tab can
+# attach and continue from the step it already persisted; the ring is bounded and
+# rotates on every confirmed step-persist. This caps the un-persisted tail between
+# rotations — an overflow evicts the oldest frames and a late attach falls back to
+# 204 -> degraded poll, so correctness never depends on the size. Default 4194304
+# (4MB); a 0/invalid value falls back to the default. The per-subscriber backpressure
+# cap is derived as 2x this value. Only meaningful with AI_CHAT_RESUMABLE_STREAM on.
+# AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES=4194304
 
 # --- Run lifecycle tunables (#487) ---
 # These govern the universal run machinery (every turn is now a first-class run,

.gitignore

@@ -29,6 +29,10 @@ packages/mcp/build/
 # is a build artifact like build/ — never committed, always fresh.
 packages/mcp/src/registry-stamp.generated.ts
 
+# token-estimate compiled output (#490; built in CI/Docker via `pnpm build` /
+# the server `pretest`, never committed, so src/ and prod can never diverge).
+packages/token-estimate/dist/
+
 # Logs
 logs
 *.log

CHANGELOG.md

@@ -336,6 +336,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **A long AI chat no longer bricks on the model's context window, and each turn
+  stops re-persisting the whole tool-output history.** Tool outputs are now
+  stored ONCE, in `metadata.parts`; the `tool_calls` trace keeps only per-step
+  outcome flags (a v2 trace shape), ending the O(N²) write amplification that
+  re-wrote every prior output on every step (measured on a live Postgres via the
+  `pg_current_wal_lsn()` delta: the trace column shrank ~3200×, the full
+  assistant row ~51%). The persisted record is unchanged in content — the full
+  history still lives in `metadata.parts`. At REPLAY time only, the history sent
+  to the provider is now bounded by a deterministic, prompt-cache-friendly token
+  budget: `floor(0.7 × chatContextWindow)` when a window is configured (no cap —
+  anti-brick protection, not a cost limiter), a flat 100k fallback for installs
+  with no window set (exactly the ones that hit terminal overflow), or off when
+  the window is explicitly `0`. Trimming truncates old tool outputs first, then
+  mechanically collapses the oldest turns, always keeping the recent turns full
+  and the tool-call/result pairing balanced. A provider context-overflow 400 is
+  now classified and used as a reactive signal: the row is stamped so the NEXT
+  turn re-trims aggressively (0.5×), which un-bricks a chat that just 400'd. The
+  client token badge and the server budgeter now share one estimator (new
+  `@docmost/token-estimate` package) so they can never diverge. Deferred-tool
+  activation is also cached in the chat metadata to avoid re-resolving it each
+  turn. (#490)
 - **A chat with one malformed message part no longer 500s on every turn, and a
   failed send no longer duplicates the user's message.** Incoming client parts
   are now whitelisted to `text` (a forged tool-result part can no longer reach

apps/client/package.json

@@ -22,6 +22,7 @@
     "@casl/react": "5.0.1",
     "@docmost/editor-ext": "workspace:*",
     "@docmost/prosemirror-markdown": "workspace:*",
+    "@docmost/token-estimate": "workspace:*",
     "@excalidraw/excalidraw": "0.18.0-3a5ef40",
     "@mantine/core": "8.3.18",
     "@mantine/dates": "8.3.18",

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

@@ -58,8 +58,11 @@ import ConversationList from "@/features/ai-chat/components/conversation-list.ts
 import ChatThread from "@/features/ai-chat/components/chat-thread.tsx";
 import {
   exportAiChat,
+  getAiChatMessagesDelta,
   stopRun,
 } from "@/features/ai-chat/services/ai-chat-service.ts";
+import { mergeDeltaRowsIntoPages } from "@/features/ai-chat/utils/resume-helpers.ts";
+import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
 import { useChatSession } from "@/features/ai-chat/hooks/use-chat-session.ts";
 import {
   shouldCollapseOnOutsidePointer,
@@ -269,17 +272,64 @@ export default function AiChatWindow() {
   const { data: messageRows, isLoading: messagesLoading } =
     useAiChatMessagesQuery(
       activeChatId ?? undefined,
-      // DELIBERATELY DUMB: poll every 2.5s WHILE ARMED, otherwise off. NO error
-      // checks (TanStack resets fetchFailureCount each fetch; the poll must survive
-      // a server restart), NO tail checks, NO cap here — the settled/stalled/idle-cap
-      // semantics all live in ChatThread's FSM, which disarms via onResumeFallback.
-      () => (degradedPoll === true ? 2500 : false),
-      // #344: gate on windowOpen too — no message history is fetched (and no
-      // degraded poll runs) while the window is closed; it loads when the window
-      // opens with an active chat.
+      // #491: the full infinite-query no longer POLLS. It seeds the thread ONCE; the
+      // degraded fallback now runs a DELTA poller (below) that augments THIS cache
+      // idempotently, instead of refetching every page (with full parts) every 2.5s.
+      false,
+      // #344: gate on windowOpen too — no message history is fetched while the window
+      // is closed; it loads when the window opens with an active chat.
       windowOpen,
     );
 
+  // #491 degraded DELTA poll. While armed (degradedPoll) and the window is open on a
+  // chat, poll POST /ai-chat/messages/delta every 2.5s: it returns only the rows
+  // CHANGED since the previous cursor (+ the run fact) in ONE round-trip. We merge
+  // those rows into the SAME infinite-query cache the thread reads (idempotently by
+  // id — the delta's overlap window re-delivers rows), so the thread's reconcile
+  // effect follows the detached run to its terminal row from a fraction of the wire
+  // cost. The run-fact settle stays the thread FSM's job (row-status reconcile), so
+  // we do NOT double-poll /run here. Cursor resets when the chat changes / disarms.
+  const deltaCursorRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    deltaCursorRef.current = undefined;
+  }, [activeChatId, degradedPoll]);
+  useEffect(() => {
+    if (!degradedPoll || !windowOpen || !activeChatId) return;
+    const chatId = activeChatId;
+    let cancelled = false;
+    const tick = async (): Promise<void> => {
+      try {
+        const res = await getAiChatMessagesDelta(chatId, deltaCursorRef.current);
+        if (cancelled) return;
+        deltaCursorRef.current = res.cursor;
+        if (res.rows.length > 0) {
+          queryClient.setQueryData(
+            AI_CHAT_MESSAGES_RQ_KEY(chatId),
+            (
+              old:
+                | {
+                    pages: { items: IAiChatMessageRow[]; meta: unknown }[];
+                    pageParams: unknown[];
+                  }
+                | undefined,
+            ) =>
+              old
+                ? { ...old, pages: mergeDeltaRowsIntoPages(old.pages, res.rows) }
+                : old,
+          );
+        }
+      } catch {
+        // Transient failure (e.g. a server restart mid-run): swallow and retry on
+        // the next tick — the poll must survive a bounce, like the old dumb refetch.
+      }
+    };
+    const id = setInterval(() => void tick(), 2500);
+    return () => {
+      cancelled = true;
+      clearInterval(id);
+    };
+  }, [degradedPoll, windowOpen, activeChatId, queryClient]);
+
   // #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
   // this workspace. When the feature is off no runs are ever created, so the
   // resume attempt would only ever 204; gating ChatThread's resume on it avoids a

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

@@ -172,9 +172,18 @@ function resetState() {
   h.state.getRun.mockResolvedValue({ run: null, message: null });
 }
 
+// #491: the streaming tail carries a persisted step frontier (metadata.stepsPersisted),
+// which the tail-only attach reads as `n` in `?anchor=<id>&n=<n>`. Seeded WHOLE now.
 const streamingTail = () => [
   row("u1", "user", undefined, "hi"),
-  row("a1", "assistant", "streaming", "partial"),
+  {
+    id: "a1",
+    role: "assistant",
+    content: "partial",
+    status: "streaming",
+    createdAt: "2026-01-01T00:00:00Z",
+    metadata: { stepsPersisted: 2 },
+  } as IAiChatMessageRow,
 ];
 const settledTail = () => [
   row("u1", "user", undefined, "hi"),
@@ -335,20 +344,24 @@ describe("ChatThread — send now", () => {
     expect(screen.getAllByLabelText("Remove queued message")).toHaveLength(1);
   });
 
-  it("Stop then a REAL network-drop finish exits to idle (honor-in-stopping), NOT a false reconnect", () => {
+  it("Stop then a REAL network-drop finish exits to idle (honor-in-stopping), NOT a false reconnect", async () => {
     // Regression for the disconnect-first reorder: on the STOP path, even a drop-
     // form finish { isError:true, isDisconnect:true } arriving in `stopping` must be
     // HONORED (reducer) and exit to idle — it must NOT enter the reconnect ladder.
     startLocalStreamWithRun(); // live local stream, autonomous
     fireEvent.click(screen.getByLabelText("Stop")); // STOP_REQUESTED -> stopping
     h.state.error = { message: "Failed to fetch" };
-    act(() => {
+    // #491: the disconnect re-seeds from persist (async getRun) before dispatching
+    // FINISH_DISCONNECT, which the reducer HONORS in `stopping` -> idle. Flush it.
+    await act(async () => {
       h.state.onFinish?.({
         message: { id: "a1", role: "assistant", parts: [] },
         isAbort: false,
         isDisconnect: true,
         isError: true,
       });
+      await Promise.resolve();
+      await Promise.resolve();
     });
     expect(screen.queryByText(/reconnecting/i)).toBeNull();
   });
@@ -803,19 +816,24 @@ describe("ChatThread — resume (attach) machinery", () => {
     expect(h.state.resumeStream).not.toHaveBeenCalled();
   });
 
-  it("strips the streaming tail from the seed, keeps a user tail whole", () => {
+  it("#491 tail-only: seeds the streaming tail WHOLE (no strip), keeps a user tail whole", () => {
     renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
-    expect(h.state.seededMessages).toHaveLength(1);
+    // MUTATION-VERIFY: re-introduce the seed-strip and this goes red — the streaming
+    // tail (steps 0..N-1) MUST be seeded so the SDK continuation appends the tail to
+    // the RIGHT message. Both rows (user + assistant) are seeded.
+    expect(h.state.seededMessages).toHaveLength(2);
     cleanup();
     resetState();
     renderThread({ autonomousRunsEnabled: true, initialRows: userTail() });
     expect(h.state.seededMessages).toHaveLength(1);
   });
 
-  it("builds the attach URL with expect=live&anchor only for a stripped streaming tail", () => {
+  it("#491 tail-only: builds the attach URL with ?anchor=&n= from the persisted step frontier", () => {
     renderThread({ autonomousRunsEnabled: true, initialRows: streamingTail() });
+    // n=2 comes from a1's metadata.stepsPersisted (MUTATION-VERIFY: hardcode n=0 and
+    // this fails). No `expect=live` param anymore.
     expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream?expect=live&anchor=a1",
+      "/api/ai-chat/runs/c1/stream?anchor=a1&n=2",
     );
     cleanup();
     resetState();
@@ -839,39 +857,41 @@ describe("ChatThread — resume (attach) machinery", () => {
     });
   }
 
-  it("204 on a streaming tail: restore + invalidate + onResumeFallback(true)", async () => {
+  it("204 on a streaming tail: NO restore (row kept) + invalidate + onResumeFallback(true)", async () => {
     const { onResumeFallback, invalidateSpy } = renderThread({
       autonomousRunsEnabled: true,
       initialRows: streamingTail(),
     });
     await attachFetch({ status: 204, ok: false });
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1); // restore
+    // #491 tail-only: the anchor row was never stripped, so there is NOTHING to
+    // restore. MUTATION-VERIFY: re-add a restore setMessages here and it goes red.
+    expect(h.state.setMessages).not.toHaveBeenCalled();
     expect(invalidateSpy).toHaveBeenCalledWith({
       queryKey: ["ai-chat-messages", "c1"],
     });
     expect(onResumeFallback).toHaveBeenCalledWith(true);
   });
 
-  it("F7 restart-survival: a 500 attach failure restores the row AND arms the poll", async () => {
+  it("F7 restart-survival: a 500 attach failure arms the poll WITHOUT a restore", async () => {
     const { onResumeFallback, invalidateSpy } = renderThread({
       autonomousRunsEnabled: true,
       initialRows: streamingTail(),
     });
     await attachFetch({ status: 500, ok: false });
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
+    expect(h.state.setMessages).not.toHaveBeenCalled();
     expect(invalidateSpy).toHaveBeenCalledWith({
       queryKey: ["ai-chat-messages", "c1"],
     });
     expect(onResumeFallback).toHaveBeenCalledWith(true);
   });
 
-  it("F7 restart-survival: a network throw restores the row AND arms the poll", async () => {
+  it("F7 restart-survival: a network throw arms the poll WITHOUT a restore", async () => {
     const { onResumeFallback, invalidateSpy } = renderThread({
       autonomousRunsEnabled: true,
       initialRows: streamingTail(),
     });
     await attachFetch(new Error("network down"), true);
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1);
+    expect(h.state.setMessages).not.toHaveBeenCalled();
     expect(invalidateSpy).toHaveBeenCalledWith({
       queryKey: ["ai-chat-messages", "c1"],
     });
@@ -931,7 +951,7 @@ describe("ChatThread — resume (attach) machinery", () => {
     expect(h.state.sendMessage).not.toHaveBeenCalled();
   });
 
-  it("an empty resumed message (starved replay) restores the row AND arms the poll", () => {
+  it("an empty resumed message (starved replay) arms the poll WITHOUT a restore", () => {
     h.state.status = "ready";
     const { onResumeFallback } = renderThread({
       autonomousRunsEnabled: true,
@@ -947,7 +967,9 @@ describe("ChatThread — resume (attach) machinery", () => {
         isError: false,
       });
     });
-    expect(h.state.setMessages).toHaveBeenCalledTimes(1); // restore
+    // #491 tail-only: the seeded steps 0..N-1 are still on screen (the SDK
+    // continuation never wiped them), so there is nothing to restore — just poll.
+    expect(h.state.setMessages).not.toHaveBeenCalled();
     expect(onResumeFallback).toHaveBeenCalledWith(true); // arm
   });
 
@@ -995,24 +1017,41 @@ describe("ChatThread — live reconnect + stalled", () => {
     cleanup();
   });
 
+  // #491: the authoritative PERSISTED assistant row `getRun` projects on a local
+  // disconnect — the re-seed source. Its metadata.stepsPersisted becomes `n`.
+  const persistedAnchor = (steps = 3) => ({
+    run: { id: "run-1", status: "running" },
+    message: {
+      id: "a2",
+      role: "assistant",
+      content: "persisted 0..N-1",
+      status: "streaming",
+      createdAt: "2026-01-01T00:00:00Z",
+      metadata: { stepsPersisted: steps },
+    },
+  });
+
   // A REAL live SSE drop. ai@6.0.207 emits BOTH { isError:true, isDisconnect:true }
-  // for a network TypeError AND sets useChat `error` — NOT the { isError:false,
-  // error:null } form the old tests fed. This is the form browser QA hit; with the
-  // buggy isError-first routing OR without the errorView render-gate these tests go
-  // red (a real drop surfaces the terminal error banner, masking the reconnect
-  // ladder). MUTATION-VERIFY of disconnect-first + the errorView phase-gate.
-  function disconnect(message: unknown = liveMsg) {
+  // for a network TypeError AND sets useChat `error`. #491: an autonomous local drop
+  // now RE-SEEDS from persist (async getRun) BEFORE entering the reconnect ladder, so
+  // this helper is async and flushes the getRun microtask before returning.
+  async function disconnect(message: unknown = liveMsg) {
     h.state.error = { message: "Failed to fetch" }; // the SDK sets error on the drop
-    act(() => {
+    await act(async () => {
       h.state.onFinish?.({
         message,
         isAbort: false,
         isDisconnect: true,
         isError: true,
       });
+      // Flush the getRun().then re-seed + the deferred FINISH_DISCONNECT dispatch.
+      await Promise.resolve();
+      await Promise.resolve();
     });
   }
   function renderLive() {
+    // The persisted-anchor read the local disconnect performs to re-seed from persist.
+    h.state.getRun.mockResolvedValue(persistedAnchor());
     const view = renderThread({
       autonomousRunsEnabled: true,
       initialRows: settledTail(),
@@ -1032,35 +1071,80 @@ describe("ChatThread — live reconnect + stalled", () => {
     });
   }
 
-  it("a live disconnect starts a backoff reconnect (banner + resumeStream after backoff)", () => {
+  it("#491: a live disconnect RE-SEEDS from persist, then backs off to reconnect with ?anchor=&n=", async () => {
     renderLive();
-    disconnect();
+    await disconnect();
+    // The re-seed read the authoritative persisted row and replaced the live partial.
+    // MUTATION-VERIFY: skip the getRun re-seed (send `n` off the live message) and the
+    // n below no longer matches the PERSISTED stepsPersisted.
+    expect(h.state.getRun).toHaveBeenCalledWith("c1");
+    expect(h.state.setMessages).toHaveBeenCalled(); // re-seeded the store from persist
     expect(screen.getByText(/reconnecting/i)).toBeTruthy();
     expect(h.state.resumeStream).not.toHaveBeenCalled();
     advanceToAttempt(1);
     expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
+    // n=3 is the PERSISTED row's stepsPersisted (from getRun), NOT the live store.
     expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream?expect=live&anchor=a2",
+      "/api/ai-chat/runs/c1/stream?anchor=a2&n=3",
     );
   });
 
-  it("#488 (browser QA): the reconnect banner is SHOWN, not masked by the residual useChat error", () => {
+  it("#491 regression (#137/#161 dup): getRun REJECT on a live disconnect drops the live partial + nulls the anchor", async () => {
+    // The re-seed source (getRun) FAILS — a flaky-network blip (SSE + getRun both
+    // fail, network recovers in ~1s). The OLD .catch just re-entered the ladder with
+    // NO re-seed and NO filter, so the reconnect could tail-apply the registry's
+    // frames onto the live partial that ALREADY has those steps -> duplicated text.
+    renderLive();
+    h.state.getRun.mockReset();
+    h.state.getRun.mockRejectedValue(new Error("network"));
+    await disconnect(); // live partial = liveMsg (id "a2")
+    expect(h.state.getRun).toHaveBeenCalledWith("c1");
+    // THE GUARANTEE: on the getRun failure the live partial (a2) is FILTERED from the
+    // store, so the reconnect can never tail-apply already-present steps onto it.
+    // MUTATION-VERIFY: revert the .catch fix (enterReconnect only, no filter) and no
+    // setMessages call removes a2 -> this reddens.
+    const removedLivePartial = (
+      h.state.setMessages as unknown as {
+        mock: { calls: [unknown][] };
+      }
+    ).mock.calls.some(([updater]) => {
+      if (typeof updater !== "function") return false;
+      const out = (updater as (p: { id: string }[]) => { id: string }[])([
+        { id: "a2" },
+        { id: "u1" },
+      ]);
+      return !out.some((m) => m.id === "a2");
+    });
+    expect(removedLivePartial).toBe(true);
+    expect(screen.getByText(/reconnecting/i)).toBeTruthy();
+    advanceToAttempt(1);
+    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
+    // Anchor was nulled -> replay-from-start (no params) / 204 -> poll; never a stale
+    // ?anchor=&n= over the live partial.
+    expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
+      "/api/ai-chat/runs/c1/stream",
+    );
+  });
+
+  it("#488 (browser QA): the reconnect banner is SHOWN, not masked by the residual useChat error", async () => {
     // The drop sets useChat `error` (real SDK), and the terminal errorView describes
     // it ("Lost connection to the server"). The FSM phase-gate must let the
     // `reconnecting` banner WIN over that residual error. MUTATION-VERIFY: revert the
     // errorView phase-gate (show errorView whenever error is set) and the terminal
     // banner masks "reconnecting…" -> red.
     renderLive();
-    disconnect();
+    await disconnect();
     expect(h.state.error).not.toBeNull(); // the SDK error IS set during recovery
     expect(screen.getByText(/reconnecting/i)).toBeTruthy();
     // The terminal "Lost connection… reload" banner must NOT be showing.
     expect(screen.queryByText(/reload and try again/i)).toBeNull();
   });
 
-  it("#488 commit 2: a disconnect BEFORE the first assistant frame reconnects with NO anchor", () => {
+  it("#488 commit 2: a disconnect BEFORE the first assistant frame reconnects with NO anchor", async () => {
     renderLive();
-    disconnect(null); // no assistant message yet (pre-first-frame break)
+    // No persisted assistant row for a pre-first-frame break -> no anchor.
+    h.state.getRun.mockResolvedValue({ run: null, message: null });
+    await disconnect(null); // no assistant message yet (pre-first-frame break)
     expect(screen.getByText(/reconnecting/i)).toBeTruthy();
     expect(
       screen.queryByText("Connection lost — the answer was interrupted."),
@@ -1074,7 +1158,7 @@ describe("ChatThread — live reconnect + stalled", () => {
 
   it("a live re-attach (2xx) clears the reconnect banner", async () => {
     renderLive();
-    disconnect();
+    await disconnect();
     advanceToAttempt(1);
     await reconnect({ status: 200, ok: true });
     expect(screen.queryByText(/reconnecting/i)).toBeNull();
@@ -1082,7 +1166,7 @@ describe("ChatThread — live reconnect + stalled", () => {
 
   it("a 204 arms the degraded poll and backs off to the next attempt", async () => {
     const { onResumeFallback } = renderLive();
-    disconnect();
+    await disconnect();
     advanceToAttempt(1);
     expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
     await reconnect({ status: 204, ok: false });
@@ -1094,7 +1178,7 @@ describe("ChatThread — live reconnect + stalled", () => {
 
   it("exhausts the attempt limit into a manual Retry, which restarts the sequence", async () => {
     renderLive();
-    disconnect();
+    await disconnect();
     for (let n = 1; n <= 5; n++) {
       advanceToAttempt(n);
       expect(h.state.resumeStream).toHaveBeenCalledTimes(n);
@@ -1112,22 +1196,23 @@ describe("ChatThread — live reconnect + stalled", () => {
   it("#488 commit 3: two breaks in a row produce two reconnect cycles", async () => {
     renderLive();
     // First break -> reconnect -> re-attach live.
-    disconnect();
+    await disconnect();
     advanceToAttempt(1);
     expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
     await reconnect({ status: 200, ok: true });
     expect(screen.queryByText(/reconnecting/i)).toBeNull();
-    // The re-attached observer stream drops AGAIN -> a SECOND reconnect cycle
-    // (the old one-shot !wasResumed gate sent this to silent poll).
-    disconnect();
+    // The re-attached observer (live-follow) stream drops AGAIN -> a SECOND reconnect
+    // cycle. #491: this too re-seeds from persist before re-attaching (never tail-
+    // applies over the live-follow partial).
+    await disconnect();
     expect(screen.getByText(/reconnecting/i)).toBeTruthy();
     advanceToAttempt(1);
     expect(h.state.resumeStream).toHaveBeenCalledTimes(2);
   });
 
-  it("does NOT reconnect when autonomous runs are disabled", () => {
+  it("does NOT reconnect when autonomous runs are disabled", async () => {
     renderThread({ autonomousRunsEnabled: false, initialRows: settledTail() });
-    disconnect();
+    await disconnect();
     expect(screen.queryByText(/reconnecting/i)).toBeNull();
     expect(
       screen.getByText("Connection lost — the answer was interrupted."),
@@ -1138,7 +1223,7 @@ describe("ChatThread — live reconnect + stalled", () => {
 
   it("#488 commit 4a: the poll idle cap surfaces a stalled banner + Retry (not silent)", async () => {
     renderLive();
-    disconnect();
+    await disconnect();
     advanceToAttempt(1);
     await reconnect({ status: 204, ok: false }); // arms the poll (reconnecting)
     // No activity for the whole idle cap -> stalled.

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

@@ -42,7 +42,7 @@ import { assistantMessageHasVisibleContent } from "@/features/ai-chat/utils/mess
 import {
   isStreamingTail,
   isSettledAssistantTail,
-  seedRows,
+  stepsPersistedOf,
   mergeById,
 } from "@/features/ai-chat/utils/resume-helpers.ts";
 import { getRun } from "@/features/ai-chat/services/ai-chat-service.ts";
@@ -266,25 +266,33 @@ export default function ChatThread({
   // is NOT one of the lifecycle flags the FSM replaced.
   const mountedRef = useRef(true);
 
-  // attachStrategy DATA (behind the resumeStream effect; #491 swaps it to tail-only
-  // WITHOUT touching the FSM). The controller is effect-owned (aborted in cleanup,
-  // I5). `stripRef`/`strippedRowRef` are the current full-replay+strip anchor.
+  // attachStrategy DATA (behind the resumeStream effect; #491 tail-only, WITHOUT
+  // touching the FSM). The controller is effect-owned (aborted in cleanup, I5).
+  // `anchorRef` is the PERSISTED assistant row that pins the run (server invariant
+  // 6) and its persisted step frontier N: it feeds `?anchor=<id>&n=<stepsPersisted>`
+  // so the tail-only attach returns frames for steps >= N (the seed carries 0..N-1).
+  // It is NOT a "stripped" row — the seed keeps every row (tail-only replaces the
+  // old full-replay+strip). Null when there is no streaming/active tail to resume.
   const attachAbortRef = useRef<AbortController | null>(null);
-  const stripRef = useRef(chatId !== null && isStreamingTail(initialRows ?? []));
-  const strippedRowRef = useRef<IAiChatMessageRow | null>(
-    stripRef.current ? (initialRows ?? [])[initialRows!.length - 1] : null,
+  const anchorRef = useRef<{ id: string; stepsPersisted: number } | null>(
+    (() => {
+      if (chatId === null || !isStreamingTail(initialRows ?? [])) return null;
+      const rows = initialRows ?? [];
+      const tail = rows[rows.length - 1];
+      return { id: tail.id, stepsPersisted: stepsPersistedOf(tail) };
+    })(),
   );
   // Effect-owned backoff timers (not lifecycle flags): the reconnect ladder and the
   // stalled inactivity cap. Cleared by the cancelReconnect effect / the cap effect.
   const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const idleCapTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
+  // #491 tail-only: seed EVERY persisted row unchanged (no strip). The streaming
+  // tail holds steps 0..N-1; the run-stream registry's tail (steps >= N) is APPENDED
+  // to it by the SDK continuation (readUIMessageStream({ message })), so it must be
+  // present in the store for the attach to continue the RIGHT message.
   const initialMessages = useMemo<UIMessage[]>(
-    () =>
-      seedRows(
-        initialRows ?? [],
-        stripRef.current && autonomousRunsEnabled === true,
-      ).map(rowToUiMessage),
+    () => (initialRows ?? []).map(rowToUiMessage),
     [initialRows],
   );
 
@@ -335,21 +343,16 @@ export default function ChatThread({
     (eff: RunEffect, epoch: number) => {
       switch (eff.type) {
         case "resumeStream": {
-          // The attach GET. Stamp the outcome's generation (I1). A reconnect
-          // attempt filters the pinned live row from the store first (the mount
-          // seed already stripped it), so the live replay's text-start rebuilds it
-          // without duplicating parts (#430).
+          // The attach GET. Stamp the outcome's generation (I1). #491 tail-only: the
+          // store already holds EXACTLY the persisted steps 0..N-1 (the mount seed IS
+          // persist; a reconnect was re-seeded from persist BEFORE FINISH_DISCONNECT
+          // scheduled it — see the onFinish disconnect handler), so there is nothing
+          // to filter here: the SDK continues that seeded message, appending the tail
+          // (steps >= N) without duplicating the pre-drop partial step.
           pendingAttachEpochRef.current = epoch;
           // The resumed stream's onFinish is stamped with THIS attach generation
           // (F1), so a superseded attempt's late finish is dropped.
           turnEpochRef.current = epoch;
-          if (machineRef.current.phase.name === "reconnecting") {
-            const anchor = strippedRowRef.current;
-            if (anchor)
-              setMessagesRef.current?.((prev) =>
-                prev.filter((m) => m.id !== anchor.id),
-              );
-          }
           void resumeStreamRef.current?.();
           break;
         }
@@ -464,18 +467,23 @@ export default function ChatThread({
       new DefaultChatTransport<UIMessage>({
         api: "/api/ai-chat/stream",
         credentials: "include",
-        prepareReconnectToStreamRequest: () => ({
-          // Build the attach URL from the REAL chat id. ?expect=live&anchor=<row id>
-          // only when a streaming tail was stripped: expect=live opts into a
-          // finished-retained replay (safe only because the row is stripped and the
-          // replay rebuilds it), and the anchor pins the replay to OUR run — a
-          // mismatching (newer) run 204s into the restore+poll path instead.
-          api: `/api/ai-chat/runs/${chatIdRef.current}/stream${
-            stripRef.current
-              ? `?expect=live&anchor=${strippedRowRef.current!.id}`
-              : ""
-          }`,
-        }),
+        prepareReconnectToStreamRequest: () => {
+          // #491 tail-only attach URL. When there is an anchor (a streaming/active
+          // tail to resume) build `?anchor=<assistantRowId>&n=<stepsPersisted>`: the
+          // server returns the TAIL — a synthetic `start` frame + frames for steps
+          // >= n, then live — which the SDK continuation appends to the seeded row.
+          // The server 204s (-> restore-noop + poll) when it cannot cover the
+          // frontier (overflow/rotation gap) or the anchor mismatches (a newer run).
+          // No anchor (a user tail / pre-first-frame break) => no params.
+          const anchor = anchorRef.current;
+          return {
+            api: `/api/ai-chat/runs/${chatIdRef.current}/stream${
+              anchor
+                ? `?anchor=${anchor.id}&n=${anchor.stepsPersisted}`
+                : ""
+            }`,
+          };
+        },
         fetch: async (input: RequestInfo | URL, init: RequestInit = {}) => {
           if ((init.method ?? "GET") !== "GET") {
             // Send path (POST). #488 commit 5: NO client 409 retry ladder anymore
@@ -562,8 +570,9 @@ export default function ChatThread({
 
   // Attach GET outcome -> FSM event. The epoch guard replaces BOTH the one-shot
   // 204 guard (noStreamHandledRef) and the unmount gate: a stale/superseded or
-  // post-DISPOSE outcome is dropped (I1). For a NONE outcome the attachStrategy
-  // recovery (restore the stripped row + invalidate for a fresh poll) runs first.
+  // post-DISPOSE outcome is dropped (I1). #491 tail-only: on a NONE outcome there is
+  // NOTHING to restore — the anchor row was never stripped from the view (the seed
+  // keeps it) — so we only invalidate for a fresh poll + dispatch the FSM event.
   const handleAttachOutcome = useCallback(
     (ep: number, wasReconnecting: boolean, live: boolean) => {
       if (ep !== epochRef.current) return; // stale generation — drop
@@ -575,10 +584,6 @@ export default function ChatThread({
         );
         return;
       }
-      if (strippedRowRef.current)
-        setMessagesRef.current?.((prev) =>
-          mergeById(prev, rowToUiMessage(strippedRowRef.current!)),
-        );
       queryClient.invalidateQueries({
         queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
       });
@@ -661,56 +666,31 @@ export default function ChatThread({
       // keeps executing server-side — must win; only a NON-disconnect error (a
       // provider 500, `{ isError:true, isDisconnect:false }`) is terminal.
       if (isDisconnect) {
-        if (wasObserver) {
-          // A resumed/attached OBSERVER stream dropped. Recover via the degraded
-          // poll (restore the stripped row only when there is no visible content;
-          // never clobber a fuller on-screen tail, invariant 9). The FSM decides
-          // reconnect-vs-poll from liveFollow (a live-follow drop reconnects again,
-          // #488 commit 3; a mount-resume drop polls).
-          if (mountedRef.current) {
-            const hasVisible = msgHasVisible;
-            if (!hasVisible && strippedRowRef.current)
-              setMessages((prev) =>
-                mergeById(prev, rowToUiMessage(strippedRowRef.current!)),
-              );
-            queryClient.invalidateQueries({
-              queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
-            });
-            dispatch({
-              type: "FINISH_DISCONNECT",
-              hasVisibleContent: hasVisible,
-              epoch: stampEpoch,
-            });
-          }
+        if (!mountedRef.current) {
           setStopNotice(null);
           return;
         }
-        // A LOCAL live turn dropped. #488 commit 2: recover by the RUN-FACT, not by
-        // the presence of an assistant message — a setup-phase break (before the
-        // first frame) still leaves a detached run writing to pages. In autonomous
-        // mode a run is active for the whole turn, so seed the run-fact from the
-        // start-metadata runId when known, else a sentinel (the attach GET goes by
-        // chatId, not runId). Pin the assistant row as the strip/anchor when present.
-        if (autonomousRunsEnabled === true && mountedRef.current) {
-          const hasAnchor =
-            message?.role === "assistant" && typeof message.id === "string";
-          if (hasAnchor) {
-            strippedRowRef.current = {
-              id: message.id,
-              role: "assistant",
-              content: "",
-              status: "streaming",
-              createdAt: new Date().toISOString(),
-              metadata: { parts: message.parts },
-            };
-            stripRef.current = true;
-          } else {
-            strippedRowRef.current = null;
-            stripRef.current = false;
-          }
+        // No detached run to recover (legacy, non-autonomous): a plain disconnect —
+        // terminal notice, no reconnect. (An observer only exists in autonomous mode,
+        // so this is always a local turn.)
+        if (autonomousRunsEnabled !== true) {
           dispatch({
-            type: "RUN_FACT",
-            runFact: { runId: extractRunId(message) ?? "pending" },
+            type: "FINISH_DISCONNECT",
+            hasVisibleContent: false,
+            epoch: stampEpoch,
+          });
+          setStopNotice("disconnect");
+          return;
+        }
+        // A mount-resume OBSERVER (one-shot resume, NOT live-follow) drop falls to
+        // the degraded POLL, which merges by id — it does NOT attach, so there is
+        // nothing to re-seed. #491 tail-only: the anchor row was never removed from
+        // the view (the seed keeps it; the continuation only APPENDED), so nothing to
+        // restore either. The FSM routes this to `polling` (ownership observer,
+        // !liveFollow).
+        if (wasObserver && !machineRef.current.ctx.liveFollow) {
+          queryClient.invalidateQueries({
+            queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
           });
           dispatch({
             type: "FINISH_DISCONNECT",
@@ -718,14 +698,92 @@ export default function ChatThread({
             epoch: stampEpoch,
           });
           setStopNotice(null);
-        } else {
+          return;
+        }
+        // We will (re-)ENTER THE RECONNECT LADDER (an attach): a LOCAL live turn's
+        // first drop, OR a live-follow observer's SUBSEQUENT drop (#488 commit 3).
+        // #488 commit 2: recover by the RUN-FACT, not by the presence of an assistant
+        // message — a setup-phase break still leaves a detached run writing to pages.
+        //
+        // #491 tail-only (THE crux): the live store holds a PARTIAL step that is AHEAD
+        // of the persisted boundary; tail-applying the reconnect's step frames over it
+        // would DUPLICATE that partial step. So entering reconnecting is ALWAYS via a
+        // RE-SEED FROM PERSIST — never the live store. Fetch the authoritative
+        // persisted assistant row (`getRun` returns the projected `message`), replace
+        // the live partial by id (mergeById -> the store now holds EXACTLY steps
+        // 0..N-1), and set the anchor to `{ id, n = stepsPersisted }`. Only AFTER the
+        // re-seed is applied do we enter the ladder (FINISH_DISCONNECT schedules the
+        // backoff) — so the attach can never tail-apply over the live partial.
+        const cid = chatIdRef.current;
+        // The live-message runId is the run-fact source (the attach GET keys on
+        // chatId, so a sentinel still recovers a setup-phase break).
+        const runId = extractRunId(message ?? undefined) ?? "pending";
+        const enterReconnect = (fact: string): void => {
+          if (!mountedRef.current) return;
+          // Epoch-stamp the run-fact too (I1): the getRun rtt widens the
+          // onFinish->dispatch window, so a concurrent SEND_LOCAL during it must be
+          // able to drop this stale RUN_FACT (else it clobbers the new turn's
+          // runFact.runId). Consistent with the postRun RUN_FACT stamp.
+          dispatch({ type: "RUN_FACT", runFact: { runId: fact }, epoch: stampEpoch });
           dispatch({
             type: "FINISH_DISCONNECT",
-            hasVisibleContent: false,
+            hasVisibleContent: msgHasVisible,
             epoch: stampEpoch,
           });
-          setStopNotice("disconnect");
+        };
+        // Restore the STRUCTURAL guarantee that the live partial is never the
+        // tail-apply base: drop the live partial from the store by id and null the
+        // anchor, so the reconnect replays from step 0 into a CLEAN store (a full
+        // rebuild) or, past any rotation, 204s -> degraded poll. Used on BOTH the
+        // no-persisted-row and getRun-FAILURE paths — after this there is no path
+        // where the attach tail-applies frames onto a row that already has them
+        // (the #137/#161 duplication class).
+        const dropLivePartialAndReplayFromStart = (): void => {
+          if (message?.role === "assistant" && typeof message.id === "string") {
+            const liveId = message.id;
+            setMessagesRef.current?.((prev) =>
+              prev.filter((m) => m.id !== liveId),
+            );
+          }
+          anchorRef.current = null;
+        };
+        if (cid) {
+          void getRun(cid)
+            .then((res) => {
+              if (!mountedRef.current) return;
+              const persisted = res.message;
+              if (persisted && persisted.role === "assistant") {
+                anchorRef.current = {
+                  id: persisted.id,
+                  stepsPersisted: stepsPersistedOf(persisted),
+                };
+                // Replace the live partial with the persisted row IN PLACE by id —
+                // the re-seed from persist. The attach's tail (steps >= N) then
+                // appends to a store holding EXACTLY steps 0..N-1: no duplication.
+                setMessages((prev) => mergeById(prev, rowToUiMessage(persisted)));
+              } else {
+                // No persisted assistant row (pre-first-frame break): drop the live
+                // partial + replay from start (no anchor/n) so nothing is duplicated.
+                dropLivePartialAndReplayFromStart();
+              }
+              enterReconnect(res.run?.id ?? runId);
+            })
+            .catch(() => {
+              if (!mountedRef.current) return;
+              // Persist read FAILED: we cannot re-seed from fresh persist, and a
+              // stale mount-time anchor over the live partial would tail-apply
+              // already-present steps -> duplication (a flaky-network blip:
+              // SSE + getRun both fail, network recovers in ~1s, the registry still
+              // covers from the mount frontier). Restore the removed-filter guarantee
+              // instead: drop the live partial + replay from start / 204 -> poll.
+              dropLivePartialAndReplayFromStart();
+              enterReconnect(runId);
+            });
+        } else {
+          dropLivePartialAndReplayFromStart();
+          enterReconnect(runId);
         }
+        setStopNotice(null);
         return;
       }
       // A NON-disconnect stream error (a provider 500 etc.) -> terminal error banner.
@@ -746,11 +804,10 @@ export default function ChatThread({
         if (mountedRef.current) {
           const hasVisible = msgHasVisible;
           if (!hasVisible) {
-            // Starved replay: restore the stripped row + poll to the real terminal.
-            if (strippedRowRef.current)
-              setMessages((prev) =>
-                mergeById(prev, rowToUiMessage(strippedRowRef.current!)),
-              );
+            // Starved replay (the tail carried no new steps). #491 tail-only: the
+            // seeded steps 0..N-1 are still on screen (the SDK continuation never
+            // wiped them — `start` does not reset parts), so there is nothing to
+            // restore; just poll to the real terminal.
             queryClient.invalidateQueries({
               queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatIdRef.current),
             });
@@ -863,12 +920,12 @@ export default function ChatThread({
     const tail = rows[rows.length - 1];
     if (!tail || tail.role !== "assistant") return;
     setMessages((prev) => mergeById(prev, rowToUiMessage(tail)));
-    // Anchor-mismatch coherence: a restored stripped row A that a DIFFERENT run's
-    // row B has replaced as the tail would linger as an orphan — settle A from
-    // fresh history so no phantom row survives.
-    const stripped = strippedRowRef.current;
-    if (stripped && stripped.id !== tail.id) {
-      const historical = rows.find((r) => r.id === stripped.id);
+    // Anchor-mismatch coherence: if a DIFFERENT run's row B has replaced our anchor
+    // row A as the tail, A would linger as an orphan — reconcile A by id from FRESH
+    // PERSISTED history (not the pinned live row) so no phantom row survives.
+    const anchor = anchorRef.current;
+    if (anchor && anchor.id !== tail.id) {
+      const historical = rows.find((r) => r.id === anchor.id);
       if (historical)
         setMessages((prev) => mergeById(prev, rowToUiMessage(historical)));
     }

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

@@ -57,6 +57,31 @@ export async function stopRun(
   return req.data;
 }
 
+/**
+ * Delta poll (#491): the chat's message rows changed since `cursor` (a DB-clock
+ * timestamp echoed from the previous poll) plus the current run fact, in ONE
+ * round-trip — the degraded-poll fallback's payload, replacing the old "refetch
+ * ALL infinite-query pages every 2.5s with full parts" poll. Omit `cursor` on the
+ * first poll (returns just a fresh cursor, no rows, to start the chain). The
+ * overlap window guarantees occasional REPEATS, so the caller MUST merge rows
+ * idempotently by id (mergeById). Owner-gated server-side.
+ */
+export async function getAiChatMessagesDelta(
+  chatId: string,
+  cursor?: string,
+): Promise<{
+  rows: IAiChatMessageRow[];
+  cursor: string;
+  run: { id: string; status: string } | null;
+}> {
+  const req = await api.post<{
+    rows: IAiChatMessageRow[];
+    cursor: string;
+    run: { id: string; status: string } | null;
+  }>("/ai-chat/messages/delta", { chatId, cursor });
+  return req.data;
+}
+
 /**
  * #488: the run-fact — "is a run active on this chat?" — first-class from the
  * server (POST /ai-chat/run). Called on mount to seed the client FSM's run-fact

apps/client/src/features/ai-chat/state/run-fsm.spec.md

@@ -48,6 +48,7 @@ Legend: **†** = command-transition (bumps `epoch`, I1). Effects in `[…]`.
 | `RETRY` (manual, stalled banner) | stalled | polling(attach-none) **†** | `[armPoll]` |
 | `POLL_TERMINAL` (settled tail merged) | polling, reconnecting, stopping | idle | `[disarmPoll, cancelReconnect]`, runFact←null (I4) |
 | `POLL_IDLE_CAP` (inactivity cap) | polling, reconnecting | stalled | `[disarmPoll, cancelReconnect]` (commit 4a — no more silent) |
+| `POLL_IDLE_CAP` (inactivity cap) | stopping | idle | `[disarmPoll, cancelReconnect]`, runFact←null (Review #4: a Stop-armed poll with no SDK/terminal backstop gets a bounded exit — NOT `stalled`, Stop was already pressed so nothing to retry) |
 | `RUN_FACT{null}` (POST /run → null/terminal, 204) | reconnecting/attaching/polling/stopping | idle | `[cancelReconnect, disarmPoll]`, runFact←null (I3 fresh-negative gate) |
 | `RUN_FACT{runId}` | any | (same) | runFact←runId (pessimism toward an attempt) |
 | `STOP_REQUESTED` (user Stop) | streaming, reconnecting, polling | stopping **†** | `[stopRun, abortAttach, cancelReconnect, armPoll]` (poll drives the terminal — I4 exit by data) |
@@ -121,8 +122,7 @@ holds. **Pending column: empty.**
 | 11 | `stopPendingRef` | **FSM phase `stopping`** | the deferred stop fires from the chat-id adoption effect while `stopping` |
 | 12 | `mountedRef` | **retained (React liveness)** | orthogonal to run-lifecycle; gates imperative onFinish side-effects post-unmount. Epoch (I1) handles stale COMMAND-outcomes; DISPOSE bumps it |
 | 13 | `attemptResumeRef` | **FSM `ATTACH_START` + run-fact** | mount arms attach ONLY on a confirmed active run (commit 4b: streaming-tail status, or POST /run for a user tail) |
-| 14 | `stripRef` | **data** (attachStrategy) | strip+replay detail; the `resumeStream` effect reads it |
-| 15 | `strippedRowRef` | **data** (attachStrategy) | the anchor row |
+| 14–15 | `anchorRef {id, stepsPersisted}` | **data** (attachStrategy) | #491 tail-only: replaced `stripRef`/`strippedRowRef`. The PERSISTED assistant row that pins the run (server invariant 6) + its step frontier N; feeds `?anchor=<id>&n=<stepsPersisted>`. No strip — the seed keeps every row; entering reconnecting re-seeds from persist |
 | 16 | `attachAbortRef` | **effect-owned controller** | aborted by the `abortAttach` effect in cleanup (I5) |
 | 17–25 | `chatIdRef`, `openPageRef`, `getEditorSelectionRef`, `roleIdRef`, `stableIdRef`, `queuedRef`, `sendMessageRef`, `statusRef`, `lastForwardedChatIdRef` | **data** (identity/send mirrors) | unchanged — not lifecycle flags |
 | NEW | `pendingSupersedeRef` | **data** (send-plumbing) | the runId injected into the next `POST /stream {supersede}`; the single replacement for the 3 DELETED one-shots (#8/#9/#10) — net −2 refs |
@@ -151,8 +151,12 @@ message. Sources, in the order they update `ctx.runFact`:
 3. **Attach outcomes:** `ATTACH_LIVE` (2xx) confirms active; a 204 on a non-stripped
    path is an authoritative NEGATIVE fact → the runtime dispatches `RUN_FACT{null}`,
    which cancels recovery (I3 fresh-negative gate).
-4. **Poll (future resume-stack iteration #491):** the delta will carry the run field;
-   until then the poll drives to a terminal ROW, dispatched as `POLL_TERMINAL`.
+4. **Poll (#491, implemented):** the degraded poll now hits the delta endpoint
+   (`POST /ai-chat/messages/delta`), which ALREADY carries the run fact
+   (`run: {id, status} | null`) alongside the changed rows. The client does NOT yet
+   consume that run field — it still drives to a terminal ROW (merged by id),
+   dispatched as `POLL_TERMINAL` — so the run field rides the wire for a future
+   client that settles straight off it.
 
 Pessimism rule: a stale-but-positive fact PERMITS entering recovery (attach); the
 204 then cuts it. A fresh negative fact gates recovery OUT immediately.
@@ -178,6 +182,9 @@ Pessimism rule: a stale-but-positive fact PERMITS entering recovery (attach); th
   /run) are effect-owned and aborted in cleanup (`abortAttach` on `DISPOSE`), not
   render-phase refs. A client abort of an already-sent POST does not cancel the
   server action, so disarming on unmount is safe.
-- **attachStrategy** (strip+replay today) is behind the `resumeStream` effect; the
-  resume-stack iteration (#491) swaps it to tail-only WITHOUT touching the FSM.
+- **attachStrategy** is behind the `resumeStream` effect; #491 swapped it to
+  tail-only (`?anchor=&n=`, `anchorRef` data) WITHOUT touching the FSM. Entering
+  reconnecting always re-seeds from persist; on a getRun failure the live partial
+  is dropped + replay-from-start so it is never the tail-apply base (no #137/#161
+  duplication).
 - **Queue** stays a data structure; flush/interrupt decisions are transitions.

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

@@ -181,6 +181,12 @@ export interface IAiChatMessageRow {
   toolCalls?: unknown;
   metadata?: {
     parts?: UIMessage["parts"];
+    // #491 step-alignment anchor: the count of FINISHED steps whose parts are in
+    // THIS row, written atomically with `parts` server-side (flushAssistant). The
+    // resume client reads it as its persisted step frontier N — the tail-only
+    // attach asks the run-stream registry for the frames of step N onward (the
+    // seed already carries steps 0..N-1). Absent on pre-#491 rows -> read as 0.
+    stepsPersisted?: number;
     // AI SDK v6 `totalUsage` persisted on assistant rows. Legacy cumulative
     // figure (sum of every step's usage for the turn); kept for back-compat and
     // as the fallback for older rows that have no `contextTokens`.

apps/client/src/features/ai-chat/utils/count-stream-tokens.test.ts

@@ -6,10 +6,13 @@ describe("estimateTokens", () => {
     expect(estimateTokens("")).toBe(0);
   });
 
-  it("ceils chars/4 so any non-empty text is at least 1 token", () => {
+  // #490: migrated onto the shared @docmost/token-estimate module (chars/2.5, up
+  // from the old client-only chars/4) so the client counter and the server replay
+  // budgeter can never diverge.
+  it("ceils chars/2.5 so any non-empty text is at least 1 token", () => {
     expect(estimateTokens("a")).toBe(1);
-    expect(estimateTokens("abcd")).toBe(1);
-    expect(estimateTokens("abcde")).toBe(2);
-    expect(estimateTokens("12345678")).toBe(2);
+    expect(estimateTokens("ab")).toBe(1);
+    expect(estimateTokens("abcde")).toBe(2); // 5 / 2.5 = 2
+    expect(estimateTokens("x".repeat(10))).toBe(4); // 10 / 2.5 = 4
   });
 });

apps/client/src/features/ai-chat/utils/count-stream-tokens.ts

@@ -2,18 +2,10 @@
  * Rough client-side token estimation for AI-chat UI affordances.
  *
  * No provider streams exact per-token usage mid-stream, so any in-flight figure
- * is a CLIENT ESTIMATE (chars/≈4 heuristic). Pure + unit-testable: it never runs
- * a real BPE tokenizer (that would be O(n²) on the hot path, bloat the bundle,
- * and be wrong for Gemini/Ollama anyway). Used by the in-body reasoning counter
- * ("Thinking · N tokens").
+ * is a CLIENT ESTIMATE. This re-exports the SHARED estimator from
+ * `@docmost/token-estimate` (chars/2.5) so the in-body counter and the server's
+ * replay budgeter use the SAME heuristic — two divergent estimators would mean
+ * "the badge shows 60%" while "the budgeter already trimmed" (#490). Used by the
+ * in-body reasoning counter ("Thinking · N tokens").
  */
-
-/**
- * Rough token estimate for a piece of text using the standard chars/≈4 heuristic.
- * Returns 0 for empty/whitespace-free-of-content input, and ceils so any
- * non-empty text counts as at least one token.
- */
-export function estimateTokens(text: string): number {
-  if (!text) return 0;
-  return Math.ceil(text.length / 4);
-}
+export { estimateTokens } from "@docmost/token-estimate";

apps/client/src/features/ai-chat/utils/resume-helpers.test.ts

@@ -4,7 +4,8 @@ import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.t
 import {
   isStreamingTail,
   isSettledAssistantTail,
-  seedRows,
+  stepsPersistedOf,
+  mergeDeltaRowsIntoPages,
   mergeById,
 } from "./resume-helpers.ts";
 
@@ -12,8 +13,18 @@ function row(
   id: string,
   role: string,
   status?: string,
+  stepsPersisted?: number,
 ): IAiChatMessageRow {
-  return { id, role, content: "", status, createdAt: "2026-01-01T00:00:00Z" };
+  return {
+    id,
+    role,
+    content: "",
+    status,
+    createdAt: "2026-01-01T00:00:00Z",
+    ...(stepsPersisted !== undefined
+      ? { metadata: { stepsPersisted } }
+      : {}),
+  };
 }
 
 function makeMsg(id: string, text: string): UIMessage {
@@ -65,23 +76,92 @@ describe("isSettledAssistantTail", () => {
   });
 });
 
-describe("seedRows", () => {
-  const rows = [row("u1", "user"), row("a1", "assistant", "streaming")];
-
-  it("returns the rows unchanged when not stripping", () => {
-    expect(seedRows(rows, false)).toBe(rows);
+describe("stepsPersistedOf", () => {
+  it("reads metadata.stepsPersisted", () => {
+    expect(stepsPersistedOf(row("a1", "assistant", "streaming", 3))).toBe(3);
+    expect(stepsPersistedOf(row("a1", "assistant", "streaming", 0))).toBe(0);
   });
 
-  it("drops the last row when stripping", () => {
-    const seeded = seedRows(rows, true);
-    expect(seeded).toHaveLength(1);
-    expect(seeded[0].id).toBe("u1");
+  it("defaults to 0 for a pre-#491 row (absent), null/undefined, or a bad value", () => {
+    expect(stepsPersistedOf(row("a1", "assistant", "streaming"))).toBe(0);
+    expect(stepsPersistedOf(null)).toBe(0);
+    expect(stepsPersistedOf(undefined)).toBe(0);
+    expect(
+      stepsPersistedOf({
+        id: "a1",
+        role: "assistant",
+        content: "",
+        createdAt: "x",
+        metadata: { stepsPersisted: -2 },
+      }),
+    ).toBe(0);
   });
 
-  it("returns an empty list when stripping a single-row list", () => {
-    expect(seedRows([row("a1", "assistant", "streaming")], true)).toHaveLength(
-      0,
-    );
+  it("floors a non-integer count", () => {
+    expect(
+      stepsPersistedOf({
+        id: "a1",
+        role: "assistant",
+        content: "",
+        createdAt: "x",
+        metadata: { stepsPersisted: 2.9 },
+      }),
+    ).toBe(2);
+  });
+});
+
+describe("mergeDeltaRowsIntoPages", () => {
+  const pages = () => [
+    { items: [row("u1", "user"), row("a1", "assistant", "streaming", 1)], meta: {} },
+  ];
+
+  it("returns the pages unchanged for an empty delta", () => {
+    const p = pages();
+    expect(mergeDeltaRowsIntoPages(p, [])).toBe(p);
+  });
+
+  it("appends a genuinely new row to the last page in chronological order", () => {
+    const merged = mergeDeltaRowsIntoPages(pages(), [row("a2", "assistant", "streaming", 0)]);
+    expect(merged[0].items.map((i) => i.id)).toEqual(["u1", "a1", "a2"]);
+  });
+
+  it("replaces a grown row in place (per-step growth), never appends a duplicate", () => {
+    const merged = mergeDeltaRowsIntoPages(pages(), [
+      row("a1", "assistant", "streaming", 2),
+    ]);
+    expect(merged[0].items.map((i) => i.id)).toEqual(["u1", "a1"]);
+    // the in-place replacement carries the grown step frontier.
+    expect(stepsPersistedOf(merged[0].items[1])).toBe(2);
+  });
+
+  it("does not mutate the input pages", () => {
+    const input = pages();
+    const before = input[0].items.slice();
+    mergeDeltaRowsIntoPages(input, [row("a2", "assistant", "streaming", 0)]);
+    expect(input[0].items).toEqual(before); // untouched
+  });
+
+  // #491 CONTRACT: the delta overlap window re-delivers the same rows, so merging
+  // MUST be idempotent — applying a delta twice equals applying it once (no growth,
+  // no reorder). A regression re-introduces duplicate assistant bubbles per poll.
+  it("is idempotent: applying the same delta twice equals once", () => {
+    const delta = [
+      row("a1", "assistant", "streaming", 2), // grown existing row
+      row("a2", "assistant", "streaming", 0), // new row
+    ];
+    const once = mergeDeltaRowsIntoPages(pages(), delta);
+    const twice = mergeDeltaRowsIntoPages(once, delta);
+    const thrice = mergeDeltaRowsIntoPages(twice, delta);
+    expect(once[0].items.map((i) => i.id)).toEqual(["u1", "a1", "a2"]);
+    expect(twice[0].items.map((i) => i.id)).toEqual(["u1", "a1", "a2"]);
+    expect(twice).toEqual(once);
+    expect(thrice).toEqual(once);
+  });
+
+  it("seeds a first page when the cache is empty", () => {
+    const merged = mergeDeltaRowsIntoPages([], [row("u1", "user")]);
+    expect(merged).toHaveLength(1);
+    expect(merged[0].items.map((i) => i.id)).toEqual(["u1"]);
   });
 });
 
@@ -109,4 +189,37 @@ describe("mergeById", () => {
     expect(mergeById(prev, null)).toBe(prev);
     expect(mergeById(prev, undefined)).toBe(prev);
   });
+
+  // #491 CONTRACT: the delta poll's overlap window GUARANTEES the same row is
+  // re-delivered across close polls, so merging must be IDEMPOTENT by id — merging
+  // the same row (or an equal-length list of rows) twice must not duplicate or
+  // reorder. This is the property the whole delta-poll design leans on; a
+  // regression here would re-introduce duplicate assistant bubbles on every poll.
+  it("is idempotent by id: re-merging the same row does not duplicate or reorder", () => {
+    const seed = [makeMsg("u1", "hi"), makeMsg("a1", "step 1")];
+    const repeat = makeMsg("a1", "step 1"); // the SAME row the overlap re-delivers
+    const once = mergeById(seed, repeat);
+    const twice = mergeById(once, repeat);
+    const thrice = mergeById(twice, repeat);
+    // Length is stable (no growth), order is stable (user then assistant).
+    expect(once.map((m) => m.id)).toEqual(["u1", "a1"]);
+    expect(twice.map((m) => m.id)).toEqual(["u1", "a1"]);
+    expect(thrice.map((m) => m.id)).toEqual(["u1", "a1"]);
+    // The repeated merge converges: the row is replaced in place, never appended.
+    expect(twice[1]).toBe(repeat);
+  });
+
+  it("is idempotent across a batch of repeated + grown rows (delta re-delivery)", () => {
+    // A delta poll re-delivers a1 (unchanged) and a2 (grown one step). Applying the
+    // batch twice must equal applying it once — the poll can re-send either.
+    const start = [makeMsg("u1", "hi"), makeMsg("a1", "done")];
+    const batch = [makeMsg("a1", "done"), makeMsg("a2", "grown step 2")];
+    const apply = (list: typeof start) =>
+      batch.reduce((acc, row) => mergeById(acc, row), list);
+    const once = apply(start);
+    const twice = apply(once);
+    expect(once.map((m) => m.id)).toEqual(["u1", "a1", "a2"]);
+    expect(twice.map((m) => m.id)).toEqual(["u1", "a1", "a2"]);
+    expect(twice).toEqual(once);
+  });
 });

apps/client/src/features/ai-chat/utils/resume-helpers.ts

@@ -11,9 +11,10 @@ import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.t
 
 /**
  * A STREAMING tail: the last persisted row is an assistant row still marked
- * `status === 'streaming'`. Such a tail is stripped from the seed and rebuilt by
- * the replay (`expect=live`), since the SDK's `text-start` always pushes a new
- * part and replaying over a seeded in-progress row would duplicate its text.
+ * `status === 'streaming'`. #491 (tail-only): such a tail is seeded UNCHANGED —
+ * it carries the persisted steps 0..N-1 — and the run-stream registry's tail
+ * (frames for steps >= N) is APPENDED to it by the SDK's `readUIMessageStream`
+ * continuation. Only the presence of this tail decides WHETHER to attach.
  */
 export function isStreamingTail(rows: IAiChatMessageRow[]): boolean {
   const tail = rows[rows.length - 1];
@@ -32,15 +33,61 @@ export function isSettledAssistantTail(rows: IAiChatMessageRow[]): boolean {
 }
 
 /**
- * Seed rows for `useChat`: return the rows unchanged, or without the last row when
- * `strip` is set (the streaming tail is stripped so the live replay rebuilds it
- * without duplicating parts).
+ * #491 tail-only anchor: the count of FINISHED steps whose parts are persisted in
+ * THIS assistant row (`metadata.stepsPersisted`), written atomically with `parts`
+ * server-side. The resume client reads it as its persisted step frontier N — the
+ * tail-only attach asks the run-stream registry for the frames of step N onward
+ * (the seed already carries steps 0..N-1). Absent on pre-#491 rows => 0.
  */
-export function seedRows(
+export function stepsPersistedOf(
+  row: IAiChatMessageRow | null | undefined,
+): number {
+  const n = row?.metadata?.stepsPersisted;
+  return typeof n === "number" && n >= 0 ? Math.floor(n) : 0;
+}
+
+/** One page of the messages infinite-query cache (`{ items, meta }`). */
+export interface IMessagePage {
+  items: IAiChatMessageRow[];
+  meta: unknown;
+}
+
+/**
+ * #491 delta-poll merge: upsert the delta poll's `rows` into the messages
+ * infinite-query page structure IDEMPOTENTLY by id. The delta endpoint's overlap
+ * window GUARANTEES occasional REPEATS, so this MUST converge: a row already
+ * present is REPLACED IN PLACE (per-step growth of an in-progress row), a new row
+ * is APPENDED to the last page in chronological order (the server returns delta
+ * rows oldest-first). Applying the same delta twice equals applying it once. Never
+ * mutates the input pages (returns fresh page objects with cloned item arrays).
+ */
+export function mergeDeltaRowsIntoPages(
+  pages: IMessagePage[],
   rows: IAiChatMessageRow[],
-  strip: boolean,
-): IAiChatMessageRow[] {
-  return strip ? rows.slice(0, -1) : rows;
+): IMessagePage[] {
+  if (rows.length === 0) return pages;
+  const next: IMessagePage[] = pages.map((p) => ({
+    ...p,
+    items: p.items.slice(),
+  }));
+  const locate = (id: string): [number, number] | null => {
+    for (let pi = 0; pi < next.length; pi++) {
+      const ii = next[pi].items.findIndex((it) => it.id === id);
+      if (ii !== -1) return [pi, ii];
+    }
+    return null;
+  };
+  for (const row of rows) {
+    const at = locate(row.id);
+    if (at) {
+      next[at[0]].items[at[1]] = row; // replace in place — idempotent by id
+    } else if (next.length > 0) {
+      next[next.length - 1].items.push(row); // append chronologically
+    } else {
+      next.push({ items: [row], meta: undefined });
+    }
+  }
+  return next;
 }
 
 /**

apps/client/src/features/ai-chat/utils/sdk-continuation-tripwire.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import { readUIMessageStream, type UIMessage } from "ai";
+import pkg from "../../../../package.json";
+
+/**
+ * PIN-SPEC TRIP-WIRE (#491). The tail-only attach continuation relies on THREE
+ * behaviors of `ai@6.0.207`, verified line-by-line in the issue. Without this
+ * test, an `ai` bump could silently break attach (the client would append the
+ * live tail to the wrong message, or duplicate a step):
+ *
+ *   1. `readUIMessageStream({ message })` CONTINUES the passed message — it does
+ *      not start a fresh one — so the tail streamed after a re-seed is appended to
+ *      the seeded assistant row (the same DB id).
+ *   2. A `start` frame does NOT reset the existing message's parts (so the seeded
+ *      steps 0..N-1 survive; the synthetic `start` the registry prepends only
+ *      carries the run-fact metadata).
+ *   3. Text parts do NOT cross a `finish-step` boundary — a new `text-start` after
+ *      `finish-step` is a NEW part — so the reconstructed steps stay separated and
+ *      the step frontier stays meaningful.
+ *
+ * If an `ai` upgrade changes any of these, this test fails LOUD instead of the
+ * resume path silently corrupting.
+ */
+describe("ai SDK continuation trip-wire (#491, tail-only attach)", () => {
+  it("is pinned to the exact ai version the continuation was verified against", () => {
+    // A caret/range bump is exactly what would silently break attach — require an
+    // exact pin. Bumping ai MUST re-verify the behavior asserted below, then this.
+    expect((pkg as { dependencies: Record<string, string> }).dependencies.ai).toBe(
+      "6.0.207",
+    );
+  });
+
+  it("continues the seeded message: start does not reset parts, the tail appends as new parts", async () => {
+    // A seeded assistant row with ONE finished step already reconstructed.
+    const seeded: UIMessage = {
+      id: "assistant-1",
+      role: "assistant",
+      parts: [
+        { type: "step-start" },
+        { type: "text", text: "STEP0", state: "done" },
+      ],
+    } as UIMessage;
+
+    // The tail the registry delivers on re-attach: a synthetic start (run-fact),
+    // then step 1's frames, then finish. As UI-message chunks (what the SSE frames
+    // decode to).
+    const chunks = [
+      { type: "start", messageMetadata: { runId: "r1", chatId: "c1" } },
+      { type: "start-step" },
+      { type: "text-start", id: "t1" },
+      { type: "text-delta", id: "t1", delta: "STEP1" },
+      { type: "text-end", id: "t1" },
+      { type: "finish-step" },
+      { type: "finish" },
+    ];
+    const stream = new ReadableStream({
+      start(c) {
+        for (const ch of chunks) c.enqueue(ch);
+        c.close();
+      },
+    });
+
+    let last: UIMessage | undefined;
+    for await (const msg of readUIMessageStream({ message: seeded, stream })) {
+      last = msg;
+    }
+
+    expect(last).toBeDefined();
+    // Same message id (continuation, not a fresh message).
+    expect(last!.id).toBe("assistant-1");
+    // The seeded step-0 parts SURVIVED the `start` frame, and step 1 was appended
+    // as SEPARATE parts (text did not cross the finish-step boundary).
+    const shape = last!.parts.map((p) => `${p.type}:${(p as { text?: string }).text ?? ""}`);
+    expect(shape).toEqual([
+      "step-start:",
+      "text:STEP0",
+      "step-start:",
+      "text:STEP1",
+    ]);
+    // The run-fact metadata from the synthetic start frame is applied.
+    expect(last!.metadata).toMatchObject({ runId: "r1", chatId: "c1" });
+  });
+});

apps/server/package.json

@@ -23,7 +23,7 @@
     "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
     "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build",
+    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build && pnpm --filter @docmost/token-estimate build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",
@@ -44,6 +44,7 @@
     "@docmost/mcp": "workspace:*",
     "@docmost/pdf-inspector": "1.9.6",
     "@docmost/prosemirror-markdown": "workspace:*",
+    "@docmost/token-estimate": "workspace:*",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
@@ -206,6 +207,7 @@
       "^@docmost/db/(.*)$": "<rootDir>/database/$1",
       "^@docmost/transactional/(.*)$": "<rootDir>/integrations/transactional/$1",
       "^@docmost/ee/(.*)$": "<rootDir>/ee/$1",
+      "^@docmost/token-estimate$": "<rootDir>/../../../packages/token-estimate/src/index.ts",
       "^src/(.*)$": "<rootDir>/$1",
       "^@tiptap/react$": "<rootDir>/../test/stubs/tiptap-react.js"
     }

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

@@ -1,42 +1,122 @@
 import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
 
 /**
- * In-memory run-stream registry (#184 phase 1.5). A durable agent run tees its
- * SSE frames here (via `pipeUIMessageStreamToResponse({ consumeSseStream })`)
- * so a LATE tab — one that reloaded, or opened after the starter dropped — can
- * attach through `GET /ai-chat/runs/:chatId/stream`, replay the frames buffered
- * so far, and then follow the live tail as a normal streamer.
+ * In-memory run-stream registry (#184 phase 1.5, step-aligned retention #491). A
+ * durable agent run tees its SSE frames here (via
+ * `pipeUIMessageStreamToResponse({ consumeSseStream })`) so a LATE tab — one that
+ * reloaded, or opened after the starter dropped — can attach through
+ * `GET /ai-chat/runs/:chatId/stream`, be handed the TAIL past the step it already
+ * has persisted, and then follow the live tail as a normal streamer.
  *
  * This is deliberately single-process and best-effort: it holds nothing the DB
  * does not (the run + assistant row are the source of truth), so a process
  * restart simply drops in-flight entries and the client falls back to its
  * restore + degraded-poll path. The async `attach` return type is the seam for a
  * future phase-2 cross-process backend (Redis) — the interface does not change.
+ *
+ * ── #491 step-aligned retention (the OOM fix) ────────────────────────────────
+ * The old registry buffered up to 32MB of raw SSE frames PER active run (V8 ~2×
+ * in memory) and, on attach, blasted the WHOLE buffer to the socket synchronously
+ * with no drain — a handful of marathon runs on a 1GB container OOM'd. #491 caps
+ * the ring at a few MB (env-tunable, default 4MB) and keeps it there by ROTATING:
+ *
+ *  - Every buffered frame is STAMPED with a step number at tee (see ingestFrame).
+ *    Convention: the stamp of a frame is the number of `finish-step` parts seen
+ *    BEFORE it (starting at 0). The finish-step frame itself carries the current
+ *    value, THEN the counter increments. So a frame stamped `s` is the content of
+ *    the (s+1)-th step — 0-based step index `s` — and the stamp aligns EXACTLY
+ *    with `metadata.stepsPersisted`: a client whose persisted `stepsPersisted` is
+ *    N has steps 0..N-1 on disk (and in its seed) and needs the tail `stamp >= N`.
+ *
+ *  - The ring rotates ONLY on a CONFIRMED persist of step N
+ *    (`confirmPersistedStep`), dropping frames with `stamp < N` (those steps are
+ *    now on disk and a fresh client seed carries them). A NON-confirmed step is
+ *    never rotated away, so a persist FAILURE just makes the ring cover MORE
+ *    (auto-safe). This is the anti-inversion rule: a naive "rotate in .then()"
+ *    that rotated after an UNwritten step would drop a step nobody has → silent
+ *    hole. Rotation is gated on a real, successful persist.
+ *
+ *  - If the ring still exceeds its byte cap after rotation (a single fat step, or
+ *    a lagging persist), the OLDEST frames are evicted to stay bounded. Evicting a
+ *    not-yet-persisted frame opens a GAP: an attach whose N falls at or below an
+ *    evicted step answers 204 and the client degrades to restore+poll. The gap is
+ *    NOT sticky — the coverage floor is recomputed from the ring, so a later
+ *    persist that rotates past the holey steps clears it.
+ *
+ * ── attach numbering / coverage (the wire convention) ────────────────────────
+ * The step marker N comes ONLY FROM THE CLIENT (a query param). The server never
+ * reads the row to derive N — a server-side N from a stale seed would open a
+ * silent one-step hole. N is the client's persisted `stepsPersisted` (a COUNT):
+ *   - the tail it needs = frames with `stamp >= N`;
+ *   - coverage is OK ⟺ `coverageFloor(entry) <= N`, where coverageFloor is the
+ *     smallest step FULLY present in the ring (its smallest retained stamp, bumped
+ *     by one when that leading step was only partially evicted by overflow). If
+ *     `coverageFloor > N` the ring starts AFTER the client's frontier (a hole, or
+ *     the client's seed simply lagged behind a rotation) → 204 → the client
+ *     refetches (a larger N) and re-attaches.
+ * The N cutoff is applied in ALL branches, INCLUDING the finished-retained replay.
+ *
+ * ── same-tick invariants (unchanged, still load-bearing) ─────────────────────
+ * invariant 1: only the matching run may mutate/observe an entry (runId check).
+ * invariant 2: retention deletes ONLY its own entry (a replacement may own the key).
+ * invariant 3: open() over a live entry mirrors the done-path (subscribers released).
+ * invariant 4: the tail SLICE + subscriber registration happen in ONE synchronous
+ *              tick inside attach() — no await between them — so a concurrently
+ *              ingested frame is EITHER in the snapshot (buffered before the sync
+ *              block, and the just-added subscriber never sees it) OR fanned out to
+ *              the paused subscriber's `pending` (ingested after) — never both and
+ *              never neither: no loss, no duplication. NOTE (#491): the controller
+ *              now AWAITS the drain-respecting tail write BEFORE calling start(), so
+ *              frames ingested during that await accumulate in `pending`; this is
+ *              bounded by the subscriber cap (an overflow degrades start() to an
+ *              end(), a 204-equivalent). It is the SYNCHRONOUS snapshot+registration
+ *              — not a same-tick start() — that makes this correct.
+ * invariant 5: the controller wires close-cleanup BEFORE any write.
+ * invariant 6: no cross-run replay — the `anchor` (the client's assistant row id)
+ *              must match this run's assistant id, or a foreign run's transcript
+ *              would be appended to the client's message.
  */
 
 /** How long a finished entry is retained for late attach (replay + immediate end). */
 export const RUN_STREAM_RETAIN_FINISHED_MS = 30_000;
 
 /**
- * Per-run replay buffer cap. Past this the buffer is dropped (attach -> 204, and
- * the client falls back to its restore + degraded-poll path, #430).
- *
- * Raised from 4MB to 32MB (#430): marathon autonomous runs (11-25 min observed)
- * stream far more than 4MB of SSE frames, so a live disconnect mid-run would find
- * an already-overflowed buffer and could only degrade-poll instead of re-attaching
- * to the live tail. 32MB comfortably covers those runs while staying bounded.
- *
- * Memory cost: this is the WORST-CASE retained size PER ACTIVE run (the buffer is
- * freed on finish + retention, or dropped immediately on overflow). With the small
- * number of concurrent autonomous runs a single workspace realistically has, 32MB
- * each is an acceptable ceiling; the overflow->204->degraded-poll fallback remains
- * the backstop for anything larger, so correctness never depends on this bound.
+ * DEFAULT per-run replay ring cap (#491, down from 32MB). SSE frames carry
+ * UNcompacted tool outputs + framing overhead (×1.5–2 vs the persisted parts), so
+ * a "2–3 large reads + reasoning" step routinely blows past 2MB; 4MB comfortably
+ * holds a step or two of TAIL, which is all a resuming client needs (steps below
+ * its persisted frontier come from the seed, not the ring). The ring stays bounded
+ * because it rotates on every confirmed persist; this cap is only the ceiling for
+ * the un-persisted tail between rotations. Env-tunable via
+ * AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES (bytes); a 0/invalid value falls back to this.
  */
-export const RUN_STREAM_MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+export const AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
 
-// 2x the replay cap: a just-written full-replay burst alone can never trip the
-// per-subscriber cap (see controller); only a genuinely stalled socket can.
-export const SUBSCRIBER_MAX_BUFFERED_BYTES = 2 * RUN_STREAM_MAX_BUFFER_BYTES;
+// 2× the ring cap: a just-written full-tail burst alone can never trip the
+// per-subscriber cap (see controller); only a genuinely stalled socket can. This
+// derivative relationship is preserved even when the ring cap is env-overridden.
+export const SUBSCRIBER_MAX_BUFFERED_BYTES = 2 * AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES;
+
+/**
+ * A finish-step boundary frame is exactly `data: {"type":"finish-step"...}\n\n`
+ * (verified empirically against ai@6.0.207 — each UI-message-stream part is a
+ * single `data: {json}\n\n` event, never split across `data:` lines, and `type`
+ * is always the first key). A prefix match is cheaper than JSON.parse-per-frame
+ * and has no false positives: a literal `"type":"finish-step"` inside a text
+ * delta is JSON-escaped (`\"type\":...`), and the frame would start with
+ * `data: {"type":"text-delta"` anyway.
+ */
+const FINISH_STEP_FRAME_PREFIX = 'data: {"type":"finish-step"';
+
+/** Resolve the ring cap from the environment, falling back to the default. */
+function resolveMaxBufferBytes(): number {
+  const raw = process.env.AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES;
+  if (!raw) return AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0
+    ? Math.floor(parsed)
+    : AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES;
+}
 
 export interface RunStreamCallbacks {
   onFrame: (frame: string) => void;
@@ -44,6 +124,9 @@ export interface RunStreamCallbacks {
 }
 
 export interface RunStreamAttachment {
+  // The synthetic `start` frame (carrying { runId, chatId }) followed by the
+  // buffered TAIL filtered to `stamp >= N`. The controller writes these to the
+  // socket in chunks respecting drain, then calls start().
   replay: string[];
   finished: boolean;
   start(): void; // drain pending frames (order preserved) and go live
@@ -53,14 +136,19 @@ export interface RunStreamAttachment {
 interface Subscriber extends RunStreamCallbacks {
   started: boolean;
   pending: string[];
-  // Byte size of `pending`, capped at SUBSCRIBER_MAX_BUFFERED_BYTES. `start()` is
-  // called in the SAME tick as `attach()` today (see attach), so `pending` never
-  // holds more than one microtask of frames — but the async `attach` signature is
-  // a phase-2 seam: an await between attach and start would let a stalled paused
-  // subscriber buffer the WHOLE run here. The cap is the structural backstop.
+  // Byte size of `pending`, capped at the subscriber cap. `start()` is called in
+  // the SAME tick as `attach()` today, so `pending` never holds more than one
+  // microtask of frames — but the controller writes the (potentially large) tail
+  // respecting drain BEFORE start(), so a stalled socket can accumulate here; the
+  // cap is the structural backstop (an overflow degrades start() to an end()).
   pendingBytes: number;
   overflowed: boolean;
   pendingEnd: boolean;
+  // The client's step frontier N: this subscriber only receives frames with
+  // `stamp >= minStamp` (the tail past what it already persisted). Live frames
+  // always satisfy this (their stamp is the current, highest step), so it only
+  // filters the rare out-of-order below-frontier frame.
+  minStamp: number;
 }
 
 interface Entry {
@@ -68,8 +156,20 @@ interface Entry {
   // The persisted assistant row id of this run (set at bind; undefined if the
   // seed failed). Used by the attach anchor check (invariant 6).
   assistantMessageId?: string;
+  // Parallel arrays: frames[i] is the SSE string, stamps[i] its step number.
   frames: string[];
+  stamps: number[];
   bytes: number;
+  // The running step counter used to stamp the NEXT frame (number of finish-step
+  // frames seen so far).
+  currentStamp: number;
+  // The highest confirmed `stepsPersisted`: frames with stamp < persistedFloor are
+  // on disk (safe to drop, never re-buffered). Monotonic (confirmPersistedStep).
+  persistedFloor: number;
+  // The highest stamp EVICTED by an overflow (unsafe) drop, -1 if none. Used to
+  // detect a partially-evicted leading step when computing the coverage floor.
+  overflowThroughStamp: number;
+  // Sticky-for-logging only: at least one unsafe (overflow) eviction happened.
   overflowed: boolean;
   finished: boolean;
   subscribers: Set<Subscriber>;
@@ -80,6 +180,10 @@ interface Entry {
 export class AiChatStreamRegistryService implements OnModuleDestroy {
   private readonly logger = new Logger(AiChatStreamRegistryService.name);
   private readonly entries = new Map<string, Entry>(); // key: chatId
+  // Env-resolved caps (per instance) so a deployment can tune the ceiling without
+  // a code change. The subscriber cap keeps the documented 2× relationship.
+  readonly maxBufferBytes = resolveMaxBufferBytes();
+  readonly subscriberMaxBufferedBytes = 2 * this.maxBufferBytes;
 
   /**
    * Register a fresh entry at the START of a run (before any frame), so a tab
@@ -105,7 +209,11 @@ export class AiChatStreamRegistryService implements OnModuleDestroy {
     this.entries.set(chatId, {
       runId,
       frames: [],
+      stamps: [],
       bytes: 0,
+      currentStamp: 0,
+      persistedFloor: 0,
+      overflowThroughStamp: -1,
       overflowed: false,
       finished: false,
       subscribers: new Set<Subscriber>(),
@@ -150,6 +258,34 @@ export class AiChatStreamRegistryService implements OnModuleDestroy {
     void pump();
   }
 
+  /**
+   * Confirm that step `stepsPersisted` (a COUNT: steps 0..stepsPersisted-1) is on
+   * disk for this run, and ROTATE the ring: drop the buffered frames of those
+   * now-persisted steps (stamp < stepsPersisted). This is the ONLY thing that
+   * rotates the ring, and it is called ONLY after a genuinely SUCCESSFUL per-step
+   * persist (see ai-chat.service updateStreaming). A failed persist never calls
+   * it, so the ring covers more (auto-safe). Identity-checked (invariant 1) and
+   * monotonic (a stale lower count is ignored).
+   */
+  confirmPersistedStep(
+    chatId: string,
+    runId: string,
+    stepsPersisted: number,
+  ): void {
+    const entry = this.entries.get(chatId);
+    if (!entry || entry.runId !== runId) return;
+    if (!Number.isFinite(stepsPersisted) || stepsPersisted <= entry.persistedFloor)
+      return;
+    entry.persistedFloor = stepsPersisted;
+    // Clean rotation: drop the persisted steps from the head. These frames are on
+    // disk + carried by a fresh client seed, so this NEVER opens a gap.
+    while (entry.frames.length > 0 && entry.stamps[0] < stepsPersisted) {
+      entry.bytes -= Buffer.byteLength(entry.frames[0]);
+      entry.frames.shift();
+      entry.stamps.shift();
+    }
+  }
+
   /**
    * Terminate a run's entry from the OUTER catch of the stream method (a failure
    * before/while wiring the pipe, so `done` will never arrive). Identity-checked
@@ -162,36 +298,77 @@ export class AiChatStreamRegistryService implements OnModuleDestroy {
   }
 
   /**
-   * Attach to a run's stream. Async only for the phase-2 Redis seam — the body
-   * runs synchronously so the replay snapshot and the subscriber registration
-   * happen in ONE tick with no await between them (invariant 4): a frame ingested
-   * concurrently cannot slip into the gap and be lost or duplicated.
+   * Attach to a run's stream from the client's step frontier `n` (its persisted
+   * `stepsPersisted`). Async only for the phase-2 Redis seam — the body runs
+   * synchronously so the tail SLICE and the subscriber registration happen in ONE
+   * tick with no await between them (invariant 4).
    *
    * Returns null (-> the caller answers 204) when:
-   *  - there is no entry, or it overflowed (replay is gone);
-   *  - expect=live with an anchor that does not match this run's assistant id
-   *    (invariant 6: a stripped tab must never replay a FOREIGN run's transcript);
-   *  - the run finished and the caller did not expect a live tail.
-   * A finished run with expect=live yields a replay-only attachment (no
-   * subscriber registered). Otherwise a paused subscriber is registered and the
-   * caller replays `replay`, then calls start() to drain and go live.
+   *  - there is no entry;
+   *  - the `anchor` does not match this run's assistant id (invariant 6);
+   *  - the ring does not cover the client's frontier (coverageFloor > n): a hole
+   *    from overflow, or the client's seed simply lagged behind a rotation. The
+   *    client then refetches (a larger n) and re-attaches.
+   *
+   * Otherwise the attachment's `replay` is a synthetic `start` frame (the run-fact
+   * on re-attach) followed by the buffered tail filtered to `stamp >= n`. For a
+   * FINISHED run this is replay-only (no subscriber) and ends after the replay —
+   * with n = N_final that tail is just the run's `finish` frame, so the client
+   * closes the stream. For a LIVE run a paused subscriber is registered; the
+   * caller writes the replay (respecting drain) then calls start() to drain the
+   * pending frames and go live.
    */
   async attach(
     chatId: string,
-    expectLive: boolean,
     anchor: string | undefined,
+    // The client's persisted step frontier. `null` = a NOT-tail-aware client (no
+    // `n` query param) — a legacy/parameterless tab that expects the old
+    // "finished -> 204 -> poll" contract; distinct from `0` (a tail-aware client
+    // with nothing persisted yet).
+    n: number | null,
     cb: RunStreamCallbacks,
   ): Promise<RunStreamAttachment | null> {
     const entry = this.entries.get(chatId);
-    if (!entry || entry.overflowed) return null;
+    if (!entry) return null;
     // Invariant 6: cross-run replay is forbidden. Before bind, assistantMessageId
     // is undefined and mismatches any anchor -> 204 -> client restore+poll path.
-    if (expectLive && anchor && entry.assistantMessageId !== anchor) return null;
-    if (entry.finished && !expectLive) return null;
-    if (entry.finished && expectLive) {
+    if (anchor && entry.assistantMessageId !== anchor) return null;
+    // #491 regression guard (#137/#161 dup): a NOT-tail-aware client (no `n`)
+    // resuming a FINISHED run must 204 and poll — the old `finished && !expectLive`
+    // gate. Without this, a missing `n` collapsing to frontier 0 would serve the
+    // WHOLE tail of a finished, NON-rotated run (coverageFloor 0), and a
+    // parameterless client that never stripped its transcript would APPEND that
+    // full replay onto the steps it already shows -> duplicated text. A tail-aware
+    // client (n present, incl. n=0) still gets the tail past its frontier.
+    if (entry.finished && n === null) return null;
+    // A finished entry with NOTHING in the ring (aborted before the first frame,
+    // or fully overflowed) has no tail to deliver -> 204 -> the client polls.
+    if (entry.finished && entry.frames.length === 0) return null;
+    // A LIVE run with no `n` (legacy parameterless) replays from step 0 (the old
+    // behavior); a tail-aware client resumes from its frontier.
+    const frontier = n ?? 0;
+    const floor = this.coverageFloor(entry);
+    if (floor > frontier) {
+      this.logger.warn(
+        `run-stream attach gap for run=${entry.runId}: coverageFloor=${floor} ` +
+          `> client frontier=${frontier} -> 204 (client refetches + re-attaches)`,
+      );
+      return null;
+    }
+
+    const startFrame = this.buildStartFrame(chatId, entry.runId);
+    const sliceTail = (): string[] => {
+      const out: string[] = [startFrame];
+      for (let i = 0; i < entry.frames.length; i++) {
+        if (entry.stamps[i] >= frontier) out.push(entry.frames[i]);
+      }
+      return out;
+    };
+
+    if (entry.finished) {
       // Replay-only: the run is done, no subscriber is registered.
       return {
-        replay: entry.frames.slice(),
+        replay: sliceTail(),
         finished: true,
         start: () => undefined,
         unsubscribe: () => undefined,
@@ -206,15 +383,12 @@ export class AiChatStreamRegistryService implements OnModuleDestroy {
       pendingBytes: 0,
       overflowed: false,
       pendingEnd: false,
+      minStamp: frontier,
     };
+    // Register + snapshot in the SAME synchronous block (invariant 4). No await
+    // separates them, so a concurrently ingested frame cannot be lost/duplicated.
     entry.subscribers.add(sub);
-    // Snapshot in the SAME synchronous block as the registration (invariant 4).
-    const replay = entry.frames.slice();
-    // CONTRACT: the caller MUST call start() in the SAME tick as this attach()
-    // returns — no await between them. While a subscriber is paused, every frame
-    // is buffered in sub.pending; a delayed start() lets a whole run accumulate
-    // there. The pendingBytes cap (see ingestFrame) is the structural backstop if
-    // that contract is ever broken (e.g. the phase-2 Redis await seam).
+    const replay = sliceTail();
     return {
       replay,
       finished: false,
@@ -263,24 +437,83 @@ export class AiChatStreamRegistryService implements OnModuleDestroy {
     this.entries.clear();
   }
 
-  /** Buffer + fan-out a single frame. See invariant/overflow semantics inline. */
+  /** The synthetic `start` frame the tail is prefixed with — the source of the
+   *  run-fact (runId/chatId) on re-attach. A `start` frame does NOT reset the
+   *  client's message parts (ai@6.0.207 createStreamingUIMessageState), so it is
+   *  safe to prepend even when the sliced tail begins mid-message. */
+  private buildStartFrame(chatId: string, runId: string): string {
+    return `data: ${JSON.stringify({
+      type: 'start',
+      messageMetadata: { runId, chatId },
+    })}\n\n`;
+  }
+
+  /**
+   * The smallest step FULLY present in the ring: its smallest retained stamp, or
+   * (when the leading step was only partially evicted by an overflow) one past it.
+   * When the ring is empty it is the current step (only the live tail is coming).
+   * An attach at frontier `n` is covered ⟺ coverageFloor <= n.
+   */
+  private coverageFloor(entry: Entry): number {
+    // Empty ring: only the live tail is coming. The floor is the current step,
+    // but never below persistedFloor — a confirmed persist can rotate the ring
+    // empty while currentStamp still lags a beat behind on another connection, so
+    // max() keeps the invariant STRUCTURAL (a client with n = persistedFloor is
+    // always covered) rather than timing-dependent.
+    if (entry.frames.length === 0)
+      return Math.max(entry.currentStamp, entry.persistedFloor);
+    const min = entry.stamps[0];
+    return entry.overflowThroughStamp >= min ? min + 1 : min;
+  }
+
+  /**
+   * Buffer (step-stamped) + fan-out a single frame. The stamp is the number of
+   * finish-step frames seen BEFORE this one; a finish-step frame carries the
+   * current value and THEN increments the counter (so its stamp equals the 0-based
+   * index of the step it closes). Only frames at/above persistedFloor are buffered
+   * (already-persisted steps are on disk); the ring is then trimmed to the byte
+   * cap, an unsafe eviction opening a gap. Fan-out is always live (filtered per
+   * subscriber by its frontier).
+   */
   private ingestFrame(entry: Entry, frame: string): void {
-    entry.bytes += Buffer.byteLength(frame);
-    if (!entry.overflowed) {
+    const size = Buffer.byteLength(frame);
+    const stamp = entry.currentStamp;
+    if (frame.startsWith(FINISH_STEP_FRAME_PREFIX)) {
+      entry.currentStamp = stamp + 1;
+    }
+
+    // Buffer for replay only if this step is not already persisted+rotated away.
+    if (stamp >= entry.persistedFloor) {
       entry.frames.push(frame);
-      if (entry.bytes > RUN_STREAM_MAX_BUFFER_BYTES) {
-        // The crossing frame was already counted AND (below) fanned out; only the
-        // replay buffer is dropped. After overflow no more frames are buffered,
-        // but live fan-out continues.
-        entry.overflowed = true;
-        entry.frames = [];
-        this.logger.warn(
-          `run-stream buffer overflow for run=${entry.runId}; ` +
-            `late attach will 204 until the run ends`,
-        );
+      entry.stamps.push(stamp);
+      entry.bytes += size;
+      // Enforce the ring cap. Evicting a not-yet-persisted frame (stamp >=
+      // persistedFloor) opens a GAP; a leftover persisted frame (< floor) is a
+      // safe drop. Keep evicting until the ring is back under the cap.
+      while (entry.bytes > this.maxBufferBytes && entry.frames.length > 0) {
+        const evStamp = entry.stamps[0];
+        entry.bytes -= Buffer.byteLength(entry.frames[0]);
+        entry.frames.shift();
+        entry.stamps.shift();
+        if (evStamp >= entry.persistedFloor) {
+          if (evStamp > entry.overflowThroughStamp)
+            entry.overflowThroughStamp = evStamp;
+          if (!entry.overflowed) {
+            entry.overflowed = true;
+            this.logger.warn(
+              `run-stream ring overflow for run=${entry.runId}: an un-persisted ` +
+                `step was evicted to stay under ${this.maxBufferBytes}B; a late ` +
+                `attach at an evicted step will 204 until a later persist confirms`,
+            );
+          }
+        }
       }
     }
+
+    // Fan out live, filtered to each subscriber's frontier (a subscriber only
+    // wants the tail past the step it already persisted).
     for (const sub of entry.subscribers) {
+      if (stamp < sub.minStamp) continue;
       if (sub.started) {
         try {
           sub.onFrame(frame);
@@ -289,12 +522,12 @@ export class AiChatStreamRegistryService implements OnModuleDestroy {
         }
       } else {
         sub.pending.push(frame);
-        sub.pendingBytes += Buffer.byteLength(frame);
-        if (sub.pendingBytes > SUBSCRIBER_MAX_BUFFERED_BYTES) {
+        sub.pendingBytes += size;
+        if (sub.pendingBytes > this.subscriberMaxBufferedBytes) {
           // The paused subscriber's buffer overflowed — only possible if start()
-          // was delayed past the same-tick contract (the phase-2 await seam).
-          // Drop it rather than buffer the whole run; on start() it degrades to an
-          // immediate end (a 204-equivalent) instead of replaying a partial.
+          // was delayed (the controller's drain-respecting tail write, or the
+          // phase-2 await seam). Drop it rather than buffer the whole run; on
+          // start() it degrades to an immediate end (a 204-equivalent).
           sub.overflowed = true;
           sub.pending = [];
           entry.subscribers.delete(sub);

apps/server/src/core/ai-chat/ai-chat-stream-registry.spec.ts

@@ -1,19 +1,27 @@
 import {
   AiChatStreamRegistryService,
-  RUN_STREAM_MAX_BUFFER_BYTES,
+  AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES,
   RUN_STREAM_RETAIN_FINISHED_MS,
-  SUBSCRIBER_MAX_BUFFERED_BYTES,
   RunStreamCallbacks,
 } from './ai-chat-stream-registry.service';
 
 /**
- * Unit tests for the in-memory run-stream registry (#184 phase 1.5). The registry
- * is the whole of the resumable-transport contract: replay ordering, paused ->
- * live hand-off, overflow, retention, the anchor check (invariant 6), and the
- * mirror-the-done-path replace semantics (invariant 3). Every enumerated case in
- * the issue's task 1.5 has a test here.
+ * Unit tests for the in-memory run-stream registry (#184 phase 1.5, step-aligned
+ * retention #491). The registry is the whole of the resumable-transport contract:
+ * step-stamped retention, tail-only attach at the client's frontier N, the
+ * confirmed-persist ring rotation (and the anti-inversion rule), the memory bound,
+ * the overflow gap, paused -> live hand-off, retention, the anchor check
+ * (invariant 6), and the mirror-the-done-path replace semantics (invariant 3).
  */
 
+// Real ai@6 UI-message-stream SSE frames are `data: {json}\n\n`, one part each.
+const sse = (part: Record<string, unknown>): string =>
+  `data: ${JSON.stringify(part)}\n\n`;
+const finishStep = (): string => sse({ type: 'finish-step' });
+const textDelta = (id: string, delta: string): string =>
+  sse({ type: 'text-delta', id, delta });
+const finish = (): string => sse({ type: 'finish' });
+
 // A ReadableStream whose frames the test pushes explicitly, plus close/error.
 function makePushStream(): {
   stream: ReadableStream<string>;
@@ -58,6 +66,9 @@ function collector(): {
   };
 }
 
+// The tail past the synthetic start frame (replay[0] is always the start frame).
+const tail = (replay: string[]): string[] => replay.slice(1);
+
 describe('AiChatStreamRegistryService', () => {
   const CHAT = 'chat-1';
   let registry: AiChatStreamRegistryService;
@@ -71,7 +82,21 @@ describe('AiChatStreamRegistryService', () => {
     registry.onModuleDestroy();
   });
 
-  it('replays frames in arrival order (live attach)', async () => {
+  it('prepends a synthetic start frame carrying { runId, chatId }', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push('a');
+    await flush();
+
+    const c = collector();
+    const att = (await registry.attach(CHAT, 'assist-1', 0, c.cb))!;
+    const start = JSON.parse(att.replay[0].replace(/^data: /, '').trim());
+    expect(start.type).toBe('start');
+    expect(start.messageMetadata).toEqual({ runId: 'run-1', chatId: CHAT });
+  });
+
+  it('replays the buffered tail (from frontier 0) in arrival order (live attach)', async () => {
     registry.open(CHAT, 'run-1');
     const src = makePushStream();
     registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
@@ -81,13 +106,13 @@ describe('AiChatStreamRegistryService', () => {
     await flush();
 
     const c = collector();
-    const att = await registry.attach(CHAT, false, undefined, c.cb);
+    const att = await registry.attach(CHAT, 'assist-1', 0, c.cb);
     expect(att).not.toBeNull();
-    expect(att!.replay).toEqual(['a', 'b', 'c']);
+    expect(tail(att!.replay)).toEqual(['a', 'b', 'c']);
     expect(att!.finished).toBe(false);
   });
 
-  it('late attach gets the full prefix as replay plus the live tail', async () => {
+  it('late attach gets the buffered prefix as tail plus the live tail', async () => {
     registry.open(CHAT, 'run-1');
     const src = makePushStream();
     registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
@@ -96,17 +121,16 @@ describe('AiChatStreamRegistryService', () => {
     await flush();
 
     const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    expect(att.replay).toEqual(['a', 'b']);
+    const att = (await registry.attach(CHAT, 'assist-1', 0, c.cb))!;
+    expect(tail(att.replay)).toEqual(['a', 'b']);
     att.start();
-    // Live tail arrives after start().
     src.push('c');
     src.push('d');
     await flush();
     expect(c.frames).toEqual(['c', 'd']);
   });
 
-  it('a paused subscriber receives frames buffered during pause in order, then live (no loss/reorder)', async () => {
+  it('a paused subscriber receives frames buffered during pause in order, then live', async () => {
     registry.open(CHAT, 'run-1');
     const src = makePushStream();
     registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
@@ -114,81 +138,45 @@ describe('AiChatStreamRegistryService', () => {
     await flush();
 
     const c = collector();
-    // Attach (paused). Frames that arrive BEFORE start() must queue, not drop.
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    expect(att.replay).toEqual(['a']);
+    const att = (await registry.attach(CHAT, 'assist-1', 0, c.cb))!;
+    expect(tail(att.replay)).toEqual(['a']);
     src.push('b'); // arrives while paused -> pending
     src.push('c');
     await flush();
     expect(c.frames).toEqual([]); // nothing delivered yet (paused)
-    att.start(); // drains pending in order
+    att.start();
     expect(c.frames).toEqual(['b', 'c']);
-    src.push('d'); // now live
+    src.push('d');
     await flush();
     expect(c.frames).toEqual(['b', 'c', 'd']);
   });
 
   it('a run that finishes while a subscriber is paused ends it on start()', async () => {
     registry.open(CHAT, 'run-1');
+    registry.bind(CHAT, 'run-1', 'assist-1', makePushStream().stream);
     const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    // Terminate the run while the subscriber is still paused.
+    const att = (await registry.attach(CHAT, 'assist-1', 0, c.cb))!;
     registry.abortEntry(CHAT, 'run-1');
     expect(c.ended()).toBe(0); // paused: not ended yet
     att.start();
     expect(c.ended()).toBe(1); // start() drains + ends
   });
 
-  it('finished + expect=live returns a replay WITHOUT registering a subscriber', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    src.push('b');
-    src.close();
-    await flush();
-
-    const c = collector();
-    const att = (await registry.attach(CHAT, true, undefined, c.cb))!;
-    expect(att.finished).toBe(true);
-    expect(att.replay).toEqual(['a', 'b']);
-    // No subscriber registered: start()/unsubscribe are no-ops and the entry has
-    // zero subscribers.
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry.subscribers.size).toBe(0);
-    att.start();
-    expect(c.frames).toEqual([]);
-  });
-
-  it('finished WITHOUT expect=live returns null', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    src.close();
-    await flush();
-
-    const c = collector();
-    expect(await registry.attach(CHAT, false, undefined, c.cb)).toBeNull();
-  });
-
-  it('anchor mismatch with expect=live returns null (and null before bind sets assistantMessageId)', async () => {
+  it('anchor mismatch returns null (and null before bind sets assistantMessageId)', async () => {
     registry.open(CHAT, 'run-1');
     const c = collector();
     // Before bind: assistantMessageId is undefined -> mismatches any anchor.
-    expect(
-      await registry.attach(CHAT, true, 'assist-1', c.cb),
-    ).toBeNull();
+    expect(await registry.attach(CHAT, 'assist-1', 0, c.cb)).toBeNull();
 
     const src = makePushStream();
     registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
     src.push('a');
     await flush();
     // Wrong anchor -> null (cross-run replay forbidden, invariant 6).
-    expect(await registry.attach(CHAT, true, 'other-id', c.cb)).toBeNull();
+    expect(await registry.attach(CHAT, 'other-id', 0, c.cb)).toBeNull();
   });
 
-  it('matching anchor with expect=live attaches', async () => {
+  it('matching anchor attaches', async () => {
     registry.open(CHAT, 'run-1');
     const src = makePushStream();
     registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
@@ -196,97 +184,60 @@ describe('AiChatStreamRegistryService', () => {
     await flush();
 
     const c = collector();
-    const att = await registry.attach(CHAT, true, 'assist-1', c.cb);
+    const att = await registry.attach(CHAT, 'assist-1', 0, c.cb);
     expect(att).not.toBeNull();
-    expect(att!.replay).toEqual(['a']);
+    expect(tail(att!.replay)).toEqual(['a']);
   });
 
-  it('overflow: attach returns null, but the LIVE subscriber keeps receiving (incl. the crossing frame)', async () => {
+  it('a throwing onFrame ejects only that subscriber; the ingest loop stays alive', async () => {
     registry.open(CHAT, 'run-1');
     const src = makePushStream();
     registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
 
-    // A live (started) subscriber attached before the flood.
+    const bad = collector();
+    const badAtt = (await registry.attach(CHAT, 'assist-1', 0, {
+      onFrame: () => {
+        throw new Error('boom');
+      },
+      onEnd: bad.cb.onEnd,
+    }))!;
+    badAtt.start();
+
+    const good = collector();
+    const goodAtt = (await registry.attach(CHAT, 'assist-1', 0, good.cb))!;
+    goodAtt.start();
+
+    src.push('a'); // bad throws on this frame -> ejected
+    src.push('b'); // good still receives both
+    await flush();
+
+    const entry = (registry as any).entries.get(CHAT);
+    expect(entry.subscribers.size).toBe(1);
+    expect(good.frames).toEqual(['a', 'b']);
+  });
+
+  it('open() over a LIVE entry ends started subscribers once; a late done never touches the new entry (invariant 3)', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push('a');
+    await flush();
+
     const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
+    const att = (await registry.attach(CHAT, 'assist-1', 0, c.cb))!;
     att.start();
 
-    // Cap-relative so it survives a buffer-cap change (#430): a quarter-cap frame
-    // means 5 frames comfortably exceed the replay cap; the last one crosses.
-    const chunk = 'x'.repeat(Math.floor(RUN_STREAM_MAX_BUFFER_BYTES / 4));
-    for (let i = 0; i < 5; i++) src.push(chunk + i);
-    await flush();
-
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry.overflowed).toBe(true);
-    expect(entry.bytes).toBeGreaterThan(RUN_STREAM_MAX_BUFFER_BYTES);
-    // The live subscriber received ALL 5 frames, including the crossing one.
-    expect(c.frames).toHaveLength(5);
-    expect(c.frames[4]).toBe(chunk + 4);
-
-    // A NEW attach after overflow gets null (replay buffer is gone).
-    const c2 = collector();
-    expect(await registry.attach(CHAT, false, undefined, c2.cb)).toBeNull();
-  });
-
-  it('a paused subscriber whose pending buffer overflows is dropped and ends on start(); other subscribers keep receiving', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-
-    // A: paused (start() deliberately delayed to simulate the phase-2 await seam).
-    const a = collector();
-    const attA = (await registry.attach(CHAT, false, undefined, a.cb))!;
-    // B: live (started) — its delivery must be unaffected by A's overflow.
-    const b = collector();
-    const attB = (await registry.attach(CHAT, false, undefined, b.cb))!;
-    attB.start();
-
-    // Cap-relative so it survives a buffer-cap change (#430): a quarter-of-the-
-    // per-subscriber-cap frame means 5 frames exceed A's paused-pending cap while
-    // B streams every frame live.
-    const chunk = 'x'.repeat(Math.floor(SUBSCRIBER_MAX_BUFFERED_BYTES / 4));
-    for (let i = 0; i < 5; i++) src.push(chunk + i);
-    await flush();
-
-    const entry = (registry as any).entries.get(CHAT);
-    // A was dropped from the subscriber set on overflow; B (started) remains.
-    expect(entry.subscribers.size).toBe(1);
-    expect(a.frames).toEqual([]); // paused + overflowed: nothing was delivered
-    // B received every frame live (delivery unaffected by A's overflow).
-    expect(b.frames).toHaveLength(5);
-
-    // A's start() (arriving late) degrades to an immediate end, not a partial replay.
-    attA.start();
-    expect(a.frames).toEqual([]);
-    expect(a.ended()).toBe(1);
-  });
-
-  it('open() over a LIVE entry ends started subscribers exactly once and a late done does not touch the new entry (invariant 3)', async () => {
-    registry.open(CHAT, 'run-1');
-    const src = makePushStream();
-    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
-    src.push('a');
-    await flush();
-
-    const c = collector();
-    const att = (await registry.attach(CHAT, false, undefined, c.cb))!;
-    att.start(); // started subscriber on run-1
-
-    // run-2 starts on the same chat while run-1's tee is still reading.
     registry.open(CHAT, 'run-2');
-    expect(c.ended()).toBe(1); // exactly one onEnd from the replace
+    expect(c.ended()).toBe(1);
 
     const newEntry = (registry as any).entries.get(CHAT);
     expect(newEntry.runId).toBe('run-2');
     expect(newEntry.finished).toBe(false);
 
-    // The old tee now completes: its late done must NOT double-end nor delete the
-    // new entry.
     src.push('b');
     src.close();
     await flush();
-    expect(c.ended()).toBe(1); // still exactly one
+    expect(c.ended()).toBe(1);
     const still = (registry as any).entries.get(CHAT);
     expect(still).toBe(newEntry);
     expect(still.runId).toBe('run-2');
@@ -299,7 +250,6 @@ describe('AiChatStreamRegistryService', () => {
     src.push('a');
     await flush();
     const entry = (registry as any).entries.get(CHAT);
-    // Frames were NOT ingested (bind bailed), assistantMessageId untouched.
     expect(entry.frames).toEqual([]);
     expect(entry.assistantMessageId).toBeUndefined();
   });
@@ -310,32 +260,276 @@ describe('AiChatStreamRegistryService', () => {
     const entry = (registry as any).entries.get(CHAT);
     expect(entry.finished).toBe(false);
   });
+});
 
-  it('a throwing onFrame ejects only that subscriber; the ingest loop stays alive', async () => {
+/**
+ * #491 step-stamped retention: the boundary detector, tail-only slicing at the
+ * client's frontier N, the confirmed-persist rotation (+ anti-inversion), the
+ * overflow gap, the memory bound, and the finished-retained tail. All observable
+ * against the REAL registry driven through open/bind/ingest.
+ */
+describe('AiChatStreamRegistryService step-aligned retention (#491)', () => {
+  const CHAT = 'chat-s';
+  let registry: AiChatStreamRegistryService;
+
+  beforeEach(() => {
+    registry = new AiChatStreamRegistryService();
+    jest.spyOn((registry as any).logger, 'warn').mockImplementation(() => {});
+  });
+  afterEach(() => registry.onModuleDestroy());
+
+  const entryOf = () => (registry as any).entries.get(CHAT);
+
+  it('stamps frames by finish-step count, aligned with stepsPersisted', async () => {
     registry.open(CHAT, 'run-1');
     const src = makePushStream();
     registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    // step 0 content, its finish-step, step 1 content, its finish-step, finish.
+    src.push(textDelta('t0', 'a')); // stamp 0
+    src.push(finishStep()); // stamp 0 (the finish-step frame carries the pre value)
+    src.push(textDelta('t1', 'b')); // stamp 1
+    src.push(finishStep()); // stamp 1
+    src.push(finish()); // stamp 2
+    await flush();
+    const e = entryOf();
+    expect(e.stamps).toEqual([0, 0, 1, 1, 2]);
+    expect(e.currentStamp).toBe(2);
+  });
 
-    const bad = collector();
-    const badAtt = (await registry.attach(CHAT, false, undefined, {
-      onFrame: () => {
-        throw new Error('boom');
-      },
-      onEnd: bad.cb.onEnd,
-    }))!;
-    badAtt.start();
+  it('does NOT treat a text delta that merely quotes "finish-step" as a boundary', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    // A model that literally types "type":"finish-step" — JSON-escaped in the frame.
+    src.push(textDelta('t0', '"type":"finish-step"'));
+    await flush();
+    expect(entryOf().currentStamp).toBe(0); // no false boundary
+  });
 
-    const good = collector();
-    const goodAtt = (await registry.attach(CHAT, false, undefined, good.cb))!;
-    goodAtt.start();
-
-    src.push('a'); // bad throws on this frame -> ejected
-    src.push('b'); // good still receives both
+  it('tail-only: attach at N slices frames with stamp >= N', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a')); // 0
+    src.push(finishStep()); // 0
+    src.push(textDelta('t1', 'b')); // 1
+    src.push(finishStep()); // 1
+    src.push(textDelta('t2', 'c')); // 2 (in-progress)
     await flush();
 
-    const entry = (registry as any).entries.get(CHAT);
-    expect(entry.subscribers.size).toBe(1); // bad ejected, good remains
-    expect(good.frames).toEqual(['a', 'b']);
+    const c = collector();
+    // Client persisted 2 steps -> wants the tail from step 2.
+    const att = (await registry.attach(CHAT, 'assist-1', 2, c.cb))!;
+    expect(tail(att.replay)).toEqual([textDelta('t2', 'c')]);
+  });
+
+  it('attach in the MIDDLE of a step (N between finish-steps) slices from that step', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a')); // 0
+    src.push(finishStep()); // 0
+    src.push(textDelta('t1', 'b1')); // 1
+    src.push(textDelta('t1', 'b2')); // 1 (still step 1, no finish-step yet)
+    await flush();
+
+    const c = collector();
+    const att = (await registry.attach(CHAT, 'assist-1', 1, c.cb))!;
+    // Step 0's frames are dropped from the tail; the whole in-progress step 1 is kept.
+    expect(tail(att.replay)).toEqual([textDelta('t1', 'b1'), textDelta('t1', 'b2')]);
+  });
+
+  it('rotates the ring ONLY on a confirmed persist (drops stamp < N)', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a')); // 0
+    src.push(finishStep()); // 0
+    src.push(textDelta('t1', 'b')); // 1
+    await flush();
+    expect(entryOf().stamps).toEqual([0, 0, 1]);
+
+    // Confirm step 0 persisted (stepsPersisted = 1) -> drop stamp < 1.
+    registry.confirmPersistedStep(CHAT, 'run-1', 1);
+    expect(entryOf().stamps).toEqual([1]);
+    expect(entryOf().persistedFloor).toBe(1);
+  });
+
+  it('persist FAILED but the ring still fits -> attach SUCCEEDS and the tail includes step N', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a')); // 0
+    src.push(finishStep()); // 0
+    src.push(textDelta('t1', 'b')); // 1 (step 1's persist FAILED -> no confirm)
+    await flush();
+    // No confirmPersistedStep for step 1: the ring still holds step 1.
+
+    const c = collector();
+    // Client's last successful persist was step 0 -> stepsPersisted = 1.
+    const att = await registry.attach(CHAT, 'assist-1', 1, c.cb);
+    expect(att).not.toBeNull();
+    expect(tail(att!.replay)).toEqual([textDelta('t1', 'b')]); // includes step 1
+  });
+
+  it('persist failed AND the ring overflowed past N -> 204 (coverage gap)', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    // Step 0: a fat step that blows past the cap with NO persist confirmation.
+    const big = 'x'.repeat(Math.floor(AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES / 2));
+    src.push(textDelta('t0', big)); // 0
+    src.push(textDelta('t0', big)); // 0
+    src.push(textDelta('t0', big)); // 0 -> overflow evicts stamp-0 frames
+    await flush();
+    const e = entryOf();
+    expect(e.overflowed).toBe(true);
+    expect(e.bytes).toBeLessThanOrEqual(registry.maxBufferBytes);
+
+    // A client at frontier 0 falls at/below an evicted step -> gap -> null.
+    const c = collector();
+    expect(await registry.attach(CHAT, 'assist-1', 0, c.cb)).toBeNull();
+  });
+
+  it('stale N (client seed lagged behind a rotation) -> 204; after a refetch (larger N) -> success', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a')); // 0
+    src.push(finishStep()); // 0
+    src.push(textDelta('t1', 'b')); // 1
+    src.push(finishStep()); // 1
+    src.push(textDelta('t2', 'c')); // 2
+    await flush();
+    // Server confirmed steps 0 and 1 -> rotate away stamp < 2.
+    registry.confirmPersistedStep(CHAT, 'run-1', 2);
+    expect(entryOf().stamps).toEqual([2]);
+
+    // A client whose seed still says stepsPersisted = 1 -> below minStamp -> 204.
+    const stale = collector();
+    expect(await registry.attach(CHAT, 'assist-1', 1, stale.cb)).toBeNull();
+
+    // It refetches (now stepsPersisted = 2) and re-attaches -> success.
+    const fresh = collector();
+    const att = await registry.attach(CHAT, 'assist-1', 2, fresh.cb);
+    expect(att).not.toBeNull();
+    expect(tail(att!.replay)).toEqual([textDelta('t2', 'c')]);
+  });
+
+  it('overflow gap CLEARS once a later persist rotates out the holey steps', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    const big = 'x'.repeat(Math.floor(AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES / 2));
+    src.push(textDelta('t0', big)); // 0
+    src.push(textDelta('t0', big)); // 0
+    src.push(finishStep()); // 0 (still stamp 0)
+    src.push(textDelta('t1', 'small')); // 1
+    src.push(finishStep()); // 1
+    src.push(textDelta('t2', 'c')); // 2
+    await flush();
+    expect(entryOf().overflowed).toBe(true);
+
+    // Late persist confirms steps 0..1 -> rotates out the holey step-0 frames.
+    registry.confirmPersistedStep(CHAT, 'run-1', 2);
+    // A client at frontier 2 is now cleanly covered (the hole was below it).
+    const c = collector();
+    const att = await registry.attach(CHAT, 'assist-1', 2, c.cb);
+    expect(att).not.toBeNull();
+    expect(tail(att!.replay)).toEqual([textDelta('t2', 'c')]);
+  });
+
+  it('finished-retained + N = N_final -> empty tail plus the finish frame', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a')); // 0
+    src.push(finishStep()); // 0
+    src.push(finish()); // 1  (N_final = 1)
+    src.close();
+    await flush();
+    // The last step's per-step persist confirmed stepsPersisted = 1.
+    registry.confirmPersistedStep(CHAT, 'run-1', 1);
+
+    const c = collector();
+    const att = (await registry.attach(CHAT, 'assist-1', 1, c.cb))!;
+    expect(att.finished).toBe(true);
+    // Empty step tail; just the finish frame so the client's SDK closes the stream.
+    expect(tail(att.replay)).toEqual([finish()]);
+    // No subscriber registered for a finished run.
+    expect(entryOf().subscribers.size).toBe(0);
+  });
+
+  it('#491 regression (#137/#161 dup): a PARAMETERLESS attach (n=null) to a finished NON-rotated run -> 204, but n=0 still gets the tail', async () => {
+    // A finished, non-rotated run: frames present, coverageFloor 0. A missing `n`
+    // (null — a legacy/parameterless tab that never stripped its transcript) must
+    // 204 -> poll, NOT receive the whole tail it would append (duplicate). A
+    // tail-aware client (n=0 present) still resumes.
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a')); // 0
+    src.push(finishStep()); // 0
+    src.push(finish()); // 1
+    src.close();
+    await flush();
+    // NOT rotated (no confirmPersistedStep) -> stamps[0]=0, coverageFloor=0.
+    // MUTATION-VERIFY: revert the `finished && n === null -> null` gate (default n
+    // to 0) and the parameterless attach below serves the full tail instead of 204.
+    expect(await registry.attach(CHAT, 'assist-1', null, collector().cb)).toBeNull();
+    // A tail-aware client at frontier 0 IS served (the distinction: null != 0).
+    const tailAware = await registry.attach(CHAT, 'assist-1', 0, collector().cb);
+    expect(tailAware).not.toBeNull();
+    expect(tailAware!.finished).toBe(true);
+  });
+
+  it('confirmPersistedStep is monotonic and identity-checked', async () => {
+    registry.open(CHAT, 'run-1');
+    const src = makePushStream();
+    registry.bind(CHAT, 'run-1', 'assist-1', src.stream);
+    src.push(textDelta('t0', 'a'));
+    src.push(finishStep());
+    src.push(textDelta('t1', 'b'));
+    await flush();
+    registry.confirmPersistedStep(CHAT, 'run-1', 1);
+    expect(entryOf().persistedFloor).toBe(1);
+    // A stale lower count is ignored.
+    registry.confirmPersistedStep(CHAT, 'run-1', 0);
+    expect(entryOf().persistedFloor).toBe(1);
+    // A foreign runId is ignored.
+    registry.confirmPersistedStep(CHAT, 'WRONG', 5);
+    expect(entryOf().persistedFloor).toBe(1);
+  });
+
+  it('MEMORY BOUND: 5 parallel marathon runs each stream well past 32MB; each ring stays <= the cap', async () => {
+    const cap = registry.maxBufferBytes;
+    const chats = ['m0', 'm1', 'm2', 'm3', 'm4'];
+    const srcs = chats.map((chat) => {
+      registry.open(chat, `run-${chat}`);
+      const s = makePushStream();
+      registry.bind(chat, `run-${chat}`, `assist-${chat}`, s.stream);
+      return s;
+    });
+    // ~256KB frames; 160 per chat = 40MB streamed each, well past the old 32MB.
+    // Interleave a finish-step every 8 frames so steps advance realistically. No
+    // persist confirmation -> the ONLY thing keeping memory bounded is the cap.
+    const frame = 'y'.repeat(256 * 1024);
+    for (let batch = 0; batch < 20; batch++) {
+      for (let i = 0; i < 8; i++) {
+        for (const s of srcs) s.push(textDelta('t', frame));
+      }
+      for (const s of srcs) s.push(finishStep());
+      await flush(); // drain the pump so queues never hold a whole run
+    }
+    let total = 0;
+    for (const chat of chats) {
+      const e = (registry as any).entries.get(chat);
+      expect(e.bytes).toBeLessThanOrEqual(cap);
+      total += e.bytes;
+    }
+    // Total retained across all 5 runs is bounded by 5x the per-run cap — the old
+    // registry would have retained ~5x40MB = 200MB here.
+    expect(total).toBeLessThanOrEqual(cap * chats.length);
   });
 });
 
@@ -361,7 +555,7 @@ describe('AiChatStreamRegistryService retention timers', () => {
 
   it('a finished entry is removed after the retention window', () => {
     registry.open(CHAT, 'run-1');
-    registry.abortEntry(CHAT, 'run-1'); // finalize -> retention armed
+    registry.abortEntry(CHAT, 'run-1');
     expect((registry as any).entries.get(CHAT)).toBeDefined();
     jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
     expect((registry as any).entries.get(CHAT)).toBeUndefined();
@@ -369,20 +563,18 @@ describe('AiChatStreamRegistryService retention timers', () => {
 
   it('retention deletes ONLY its own entry (invariant 2)', () => {
     registry.open(CHAT, 'run-1');
-    registry.abortEntry(CHAT, 'run-1'); // arm retention for entry A
-    // Simulate the race where the key was replaced without clearing A's timer.
+    registry.abortEntry(CHAT, 'run-1');
     const sentinel = { marker: true };
     (registry as any).entries.set(CHAT, sentinel);
     jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
-    // A's timer saw entries.get(CHAT) !== A, so it did NOT delete the successor.
     expect((registry as any).entries.get(CHAT)).toBe(sentinel);
   });
 
   it('open() over a retained entry clears its timer and the successor survives', () => {
     registry.open(CHAT, 'run-1');
-    registry.abortEntry(CHAT, 'run-1'); // retained, timer armed
+    registry.abortEntry(CHAT, 'run-1');
     const clearSpy = jest.spyOn(global, 'clearTimeout');
-    registry.open(CHAT, 'run-2'); // must clear run-1's retain timer
+    registry.open(CHAT, 'run-2');
     expect(clearSpy).toHaveBeenCalled();
     jest.advanceTimersByTime(RUN_STREAM_RETAIN_FINISHED_MS + 1);
     const entry = (registry as any).entries.get(CHAT);

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

@@ -8,10 +8,12 @@ import { SUBSCRIBER_MAX_BUFFERED_BYTES } from './ai-chat-stream-registry.service
 import type { User, Workspace } from '@docmost/db/types/entity.types';
 
 /**
- * Wiring spec for the #184 phase 1.5 attach endpoint
+ * Wiring spec for the #184 phase 1.5 attach endpoint (tail-only #491)
  * (`GET /ai-chat/runs/:chatId/stream`). Owner-gated via assertOwnedChat; the
- * registry is mocked so this exercises ONLY the controller's replay/live/204/
- * cleanup wiring against a fake raw socket. Constructor order is (aiChatService,
+ * registry is mocked so this exercises ONLY the controller's tail-write/live/204/
+ * cleanup wiring against a fake raw socket. The attach signature is now
+ * `(chatId, anchor, n, cb)` — the client hands its persisted step frontier `n`
+ * and its assistant row id `anchor`. Constructor order is (aiChatService,
  * aiChatRunService, aiChatRepo, aiChatMessageRepo, aiTranscription, pageRepo,
  * streamRegistry, environment).
  */
@@ -86,8 +88,8 @@ describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
       attach: jest.fn(
         (
           _chatId: string,
-          _live: boolean,
           _anchor: string | undefined,
+          _n: number,
           cb: RunStreamCallbacks,
         ) => {
           capturedCb = cb;
@@ -156,7 +158,7 @@ describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
     expect(res.hijack).not.toHaveBeenCalled();
   });
 
-  it('threads expect=live and anchor through to the registry', async () => {
+  it('threads anchor and the numeric frontier n through to the registry', async () => {
     const { controller, streamRegistry } = makeController({
       chat: owned,
       attachment: null,
@@ -165,8 +167,8 @@ describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
     const { req } = makeReq();
     await controller.attachRunStream(
       'c1',
-      'live',
       'anchor-1',
+      '2',
       req,
       res,
       user,
@@ -174,13 +176,44 @@ describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
     );
     expect(streamRegistry.attach).toHaveBeenCalledWith(
       'c1',
-      true,
       'anchor-1',
+      2, // parsed to a number
       expect.anything(),
     );
   });
 
-  it('passes expect=false when the query is absent', async () => {
+  it('#491: an ABSENT/invalid n passes null (not 0) so a finished run 204s (not-tail-aware)', async () => {
+    // Distinguishing a MISSING `n` from `n=0` is the #137/#161 dup guard: a
+    // parameterless/legacy tab must be handed null (-> the registry 204s a finished
+    // run) rather than frontier 0 (which would serve a finished non-rotated run's
+    // whole tail). MUTATION-VERIFY: revert to `Number(n) || 0` and this asserts 0.
+    const { controller, streamRegistry } = makeController({
+      chat: owned,
+      attachment: null,
+    });
+    for (const bad of [undefined, '', 'abc']) {
+      streamRegistry.attach.mockClear();
+      const { res } = makeRawRes();
+      const { req } = makeReq();
+      await controller.attachRunStream(
+        'c1',
+        undefined,
+        bad,
+        req,
+        res,
+        user,
+        workspace,
+      );
+      expect(streamRegistry.attach).toHaveBeenCalledWith(
+        'c1',
+        undefined,
+        null,
+        expect.anything(),
+      );
+    }
+  });
+
+  it('#491: a PRESENT n=0 passes 0 (tail-aware, distinct from absent)', async () => {
     const { controller, streamRegistry } = makeController({
       chat: owned,
       attachment: null,
@@ -190,7 +223,7 @@ describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
     await controller.attachRunStream(
       'c1',
       undefined,
-      undefined,
+      '0',
       req,
       res,
       user,
@@ -198,8 +231,8 @@ describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
     );
     expect(streamRegistry.attach).toHaveBeenCalledWith(
       'c1',
-      false,
       undefined,
+      0,
       expect.anything(),
     );
   });
@@ -245,8 +278,8 @@ describe('AiChatController attach endpoint (#184 phase 1.5)', () => {
     const { req } = makeReq();
     await controller.attachRunStream(
       'c1',
-      'live',
       'a1',
+      '1',
       req,
       res,
       user,

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

@@ -0,0 +1,108 @@
+import { ForbiddenException } from '@nestjs/common';
+import { AiChatController } from './ai-chat.controller';
+import type { User, Workspace } from '@docmost/db/types/entity.types';
+
+/**
+ * Wiring spec for the #491 delta-poll endpoint (`POST /ai-chat/messages/delta`).
+ * Owner-gated via assertOwnedChat (same gate as the other reads), NOT flag-gated.
+ * The run fact rides IN the delta response (no separate /run poll). Hand-rolled
+ * mocks — no Nest graph, no DB. Constructor order: (aiChatService,
+ * aiChatRunService, aiChatRepo, aiChatMessageRepo, aiTranscription, pageRepo).
+ */
+describe('AiChatController POST /ai-chat/messages/delta (#491)', () => {
+  const user = { id: 'u1' } as User;
+  const workspace = { id: 'ws1' } as Workspace;
+
+  function makeController(opts: {
+    chat?: unknown;
+    delta?: { rows: unknown[]; cursor: string };
+    run?: unknown;
+  }) {
+    const aiChatRunService = {
+      getLatestForChat: jest.fn().mockResolvedValue(opts.run),
+    };
+    const aiChatRepo = {
+      findById: jest.fn().mockResolvedValue(opts.chat),
+    };
+    const aiChatMessageRepo = {
+      findByChatUpdatedAfter: jest
+        .fn()
+        .mockResolvedValue(opts.delta ?? { rows: [], cursor: 'C1' }),
+    };
+    const controller = new AiChatController(
+      {} as never,
+      aiChatRunService as never,
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      {} as never,
+      {} as never,
+    );
+    return { controller, aiChatRunService, aiChatRepo, aiChatMessageRepo };
+  }
+
+  it('owner-gates: a chat the user does not own throws, never reaching the repo', async () => {
+    const { controller, aiChatMessageRepo, aiChatRunService } = makeController({
+      chat: { id: 'c1', creatorId: 'someone-else' },
+    });
+    await expect(
+      controller.getMessagesDelta({ chatId: 'c1' }, user, workspace),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(aiChatMessageRepo.findByChatUpdatedAfter).not.toHaveBeenCalled();
+    expect(aiChatRunService.getLatestForChat).not.toHaveBeenCalled();
+  });
+
+  it('returns { rows, cursor, run:{id,status} } with the run fact inlined', async () => {
+    const rows = [{ id: 'm1' }];
+    const { controller } = makeController({
+      chat: { id: 'c1', creatorId: 'u1' },
+      delta: { rows, cursor: 'C2' },
+      run: { id: 'r1', status: 'running', error: 'ignored', stepCount: 3 },
+    });
+    const res = await controller.getMessagesDelta(
+      { chatId: 'c1', cursor: 'C1' },
+      user,
+      workspace,
+    );
+    expect(res).toEqual({
+      rows,
+      cursor: 'C2',
+      // ONLY id + status — never the whole run row.
+      run: { id: 'r1', status: 'running' },
+    });
+  });
+
+  it('run is null when the chat has never had a run', async () => {
+    const { controller } = makeController({
+      chat: { id: 'c1', creatorId: 'u1' },
+      run: undefined,
+    });
+    const res = await controller.getMessagesDelta(
+      { chatId: 'c1' },
+      user,
+      workspace,
+    );
+    expect(res.run).toBeNull();
+  });
+
+  it('passes cursor through, defaulting a missing cursor to null (first poll)', async () => {
+    const { controller, aiChatMessageRepo } = makeController({
+      chat: { id: 'c1', creatorId: 'u1' },
+    });
+    await controller.getMessagesDelta({ chatId: 'c1' }, user, workspace);
+    expect(aiChatMessageRepo.findByChatUpdatedAfter).toHaveBeenCalledWith(
+      'c1',
+      'ws1',
+      null,
+    );
+    await controller.getMessagesDelta(
+      { chatId: 'c1', cursor: 'CX' },
+      user,
+      workspace,
+    );
+    expect(aiChatMessageRepo.findByChatUpdatedAfter).toHaveBeenLastCalledWith(
+      'c1',
+      'ws1',
+      'CX',
+    );
+  });
+});

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

@@ -51,6 +51,7 @@ import {
   ChatIdDto,
   ExportChatDto,
   GeneratePageTitleDto,
+  GetChatDeltaDto,
   GetChatMessagesDto,
   GetRunDto,
   RenameChatDto,
@@ -63,6 +64,47 @@ import {
   SUBSCRIBER_MAX_BUFFERED_BYTES,
 } from './ai-chat-stream-registry.service';
 import { startSseHeartbeat } from './sse-resilience';
+
+/**
+ * Write the attach TAIL to the hijacked socket in chunks that RESPECT drain
+ * (#491): each `write()` that returns false (the kernel buffer is full) is awaited
+ * on the next 'drain' before continuing. The old code wrote the whole buffer
+ * synchronously, which — with the pre-#491 32MB ring — spiked memory (half the
+ * OOM). Bails immediately if the socket ended/errored mid-write. Frames that the
+ * paused registry subscriber buffers while this awaits are delivered by start().
+ */
+async function writeTailRespectingDrain(
+  raw: {
+    write(chunk: string): boolean;
+    writableEnded?: boolean;
+    destroyed?: boolean;
+    once(event: string, cb: () => void): unknown;
+    removeListener?(event: string, cb: () => void): unknown;
+  },
+  frames: string[],
+): Promise<void> {
+  for (const frame of frames) {
+    if (raw.writableEnded || raw.destroyed) return;
+    const ok = raw.write(frame);
+    if (!ok) {
+      // Kernel buffer full — wait for drain (or an early close/error) before the
+      // next chunk, so a slow reader never forces the whole tail into memory.
+      // Remove ALL three listeners once any fires, so a many-chunk tail with
+      // repeated backpressure never leaks (MaxListenersExceededWarning).
+      await new Promise<void>((resolve) => {
+        const finish = (): void => {
+          raw.removeListener?.('drain', finish);
+          raw.removeListener?.('close', finish);
+          raw.removeListener?.('error', finish);
+          resolve();
+        };
+        raw.once('drain', finish);
+        raw.once('close', finish);
+        raw.once('error', finish);
+      });
+    }
+  }
+}
 import { EnvironmentService } from '../../integrations/environment/environment.service';
 
 /**
@@ -149,6 +191,46 @@ export class AiChatController {
     );
   }
 
+  /**
+   * Delta poll (#491) — the degraded-poll fallback's payload. Returns the chat's
+   * message rows changed since `cursor` (a DB-clock timestamp from the previous
+   * poll), a FRESH cursor, AND the current run fact `{ id, status } | null`. This
+   * replaces the old degraded poll that refetched ALL infinite-query pages (full
+   * parts) every 2.5s: the client seeds once and thereafter merges only the
+   * deltas by id (the overlap window guarantees repeats — the merge is idempotent,
+   * see mergeById). The run fact rides IN the delta (a separate /run poll would
+   * double the poll QPS), so the client FSM gets the run's status on the same tick.
+   * Owner-gated via assertOwnedChat (same gate as the other read endpoints).
+   */
+  @HttpCode(HttpStatus.OK)
+  @Post('messages/delta')
+  async getMessagesDelta(
+    @Body() dto: GetChatDeltaDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ): Promise<{
+    rows: AiChatMessage[];
+    cursor: string;
+    run: { id: string; status: string } | null;
+  }> {
+    await this.assertOwnedChat(dto.chatId, user, workspace);
+    const { rows, cursor } =
+      await this.aiChatMessageRepo.findByChatUpdatedAfter(
+        dto.chatId,
+        workspace.id,
+        dto.cursor ?? null,
+      );
+    const run = await this.aiChatRunService.getLatestForChat(
+      dto.chatId,
+      workspace.id,
+    );
+    return {
+      rows,
+      cursor,
+      run: run ? { id: run.id, status: run.status } : null,
+    };
+  }
+
   /**
    * Export a chat to Markdown (#183). The DB is the single source of truth: the
    * whole transcript is loaded (oldest -> newest) and rendered server-side. Now
@@ -249,19 +331,25 @@ export class AiChatController {
   }
 
   /**
-   * Attach to a chat's live run stream (#184 phase 1.5). A late/reloaded tab
-   * replays the frames buffered so far and then follows the live tail as a normal
-   * streamer. Owner-gated via assertOwnedChat (same gate as getRun). When there is
-   * nothing to resume — no entry, a finished run without expect=live, an
-   * overflowed buffer, or an anchor that pins a DIFFERENT run — the endpoint
-   * answers 204, the ONLY "nothing to resume" signal the AI SDK's reconnect
-   * accepts (it maps 204 to a silent no-op). With AI_CHAT_RESUMABLE_STREAM off the
-   * registry is never populated, so attach always 204s.
+   * Attach to a chat's live run stream from the client's step frontier (#184 phase
+   * 1.5, tail-only #491). A late/reloaded tab hands the server the step count it
+   * has PERSISTED (`n` = the seeded row's `metadata.stepsPersisted`) and its
+   * assistant row id (`anchor`); the registry answers with the TAIL past step `n`
+   * (a synthetic `start` frame + the buffered frames stamped >= n) and then the
+   * live tail. Owner-gated via assertOwnedChat (same gate as getRun). When there
+   * is nothing to resume — no entry, a ring that does not cover the client's
+   * frontier (overflow gap, or the client's seed lagged a rotation), or an anchor
+   * that pins a DIFFERENT run (invariant 6) — the endpoint answers 204, the ONLY
+   * "nothing to resume" signal the AI SDK's reconnect accepts (it maps 204 to a
+   * silent no-op); the client then refetches (a larger n) and re-attaches. With
+   * AI_CHAT_RESUMABLE_STREAM off the registry is never populated, so attach always
+   * 204s.
    *
-   * `expect=live` opts into replaying a finished-but-retained run (safe only when
-   * the client stripped the streaming tail); `anchor` is the client's assistant
-   * row id, which must match this run's (invariant 6) or a foreign run's
-   * transcript would be replayed into the store.
+   * The step marker `n` comes ONLY from the client — the server never reads the
+   * row to derive it, because a server-side n from a stale seed would open a
+   * silent one-step hole. The tail is written to the socket in CHUNKS respecting
+   * drain (writeTailRespectingDrain): the old code synchronously blasted the whole
+   * buffer, which — with the old 32MB cap — was half the OOM.
    */
   @SkipTransform()
   @UseGuards(JwtAuthGuard, UserThrottlerGuard)
@@ -269,39 +357,49 @@ export class AiChatController {
   @Get('runs/:chatId/stream')
   async attachRunStream(
     @Param('chatId', new ParseUUIDPipe()) chatId: string,
-    @Query('expect') expect: string | undefined,
     @Query('anchor') anchor: string | undefined,
+    @Query('n') n: string | undefined,
     @Req() req: FastifyRequest,
     @Res() res: FastifyReply,
     @AuthUser() user: User,
     @AuthWorkspace() workspace: Workspace,
   ): Promise<void> {
     await this.assertOwnedChat(chatId, user, workspace); // same gate as getRun
+    // The client's persisted step frontier. #491: distinguish a MISSING/invalid `n`
+    // (null — a NOT-tail-aware, legacy/parameterless tab expecting the old
+    // "finished -> 204 -> poll" contract) from `n=0` (a tail-aware client with
+    // nothing persisted yet). Passing 0 for a missing `n` would serve a finished,
+    // non-rotated run's WHOLE tail and a parameterless client would append it onto
+    // the steps it already shows -> #137/#161 duplicate. null makes the registry
+    // 204 such a finished run (see attach); a tail-aware n=0 still resumes.
+    const frontier: number | null =
+      n === undefined || n === '' || !Number.isFinite(Number(n))
+        ? null
+        : Math.max(0, Number(n));
+    // The per-subscriber backpressure cap tracks the (env-tunable) ring cap.
+    const subscriberCap =
+      this.streamRegistry?.subscriberMaxBufferedBytes ??
+      SUBSCRIBER_MAX_BUFFERED_BYTES;
     let stopHeartbeat: () => void = () => undefined;
-    const attachment = await this.streamRegistry?.attach(
-      chatId,
-      expect === 'live',
-      anchor,
-      {
-        onFrame: (frame) => {
-          // Backpressure guard: 2x the replay cap, so the initial replay burst
-          // alone can never trip it; only a genuinely stalled socket can.
-          try {
-            if (res.raw.writableLength > SUBSCRIBER_MAX_BUFFERED_BYTES) {
-              res.raw.destroy(); // 'close' fires -> unsubscribe below
-              return;
-            }
-            if (!res.raw.writableEnded) res.raw.write(frame);
-          } catch {
-            res.raw.destroy();
+    const attachment = await this.streamRegistry?.attach(chatId, anchor, frontier, {
+      onFrame: (frame) => {
+        // Backpressure guard: 2x the ring cap, so the initial tail burst alone
+        // can never trip it; only a genuinely stalled socket can.
+        try {
+          if (res.raw.writableLength > subscriberCap) {
+            res.raw.destroy(); // 'close' fires -> unsubscribe below
+            return;
           }
-        },
-        onEnd: () => {
-          stopHeartbeat();
-          if (!res.raw.writableEnded) res.raw.end();
-        },
+          if (!res.raw.writableEnded) res.raw.write(frame);
+        } catch {
+          res.raw.destroy();
+        }
       },
-    );
+      onEnd: () => {
+        stopHeartbeat();
+        if (!res.raw.writableEnded) res.raw.end();
+      },
+    });
     if (!attachment) {
       res.status(204).send(); // the ONLY "nothing to resume" signal the SDK accepts
       return;
@@ -330,13 +428,16 @@ export class AiChatController {
         // deliberately NO Connection/Keep-Alive (hop-by-hop; Safari/HTTP2)
       });
       res.raw.flushHeaders?.();
-      for (const frame of attachment.replay) res.raw.write(frame);
+      // Write the tail in chunks respecting drain (not a synchronous blast, which
+      // was half the OOM). Frames the paused subscriber buffers meanwhile are
+      // drained by start() below; its cap is the backstop for a stalled socket.
+      await writeTailRespectingDrain(res.raw, attachment.replay);
       if (attachment.finished) {
-        res.raw.end();
+        if (!res.raw.writableEnded) res.raw.end();
         return;
       }
       stopHeartbeat = startSseHeartbeat(res.raw, 15_000);
-      attachment.start(); // drain pending accumulated during replay, go live
+      attachment.start(); // drain pending accumulated during the tail write, go live
     } catch {
       attachment.unsubscribe();
       stopHeartbeat();

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

@@ -181,7 +181,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       {} as never, // pageAccess
       { isAiChatDeferredToolsEnabled: () => false, isAiChatFinalStepLockdownEnabled: () => false } as never, // environment
     );
-    return { svc };
+    return { svc, aiChatMessageRepo };
   }
 
   const body = {
@@ -287,7 +287,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
   // 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();
+    const { svc, aiChatMessageRepo } = makeService();
     let capturedOpts: any;
     streamTextMock.mockImplementation((opts: any) => {
       capturedOpts = opts;
@@ -314,7 +314,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       runHooks: runHooks as never,
     });
     expect(capturedOpts).toBeDefined();
-    return { capturedOpts, runHooks };
+    return { capturedOpts, runHooks, aiChatMessageRepo };
   }
 
   it('F9: onStepFinish bumps the run step count, onFinish settles the run "completed" (the dominant autonomous-run path)', async () => {
@@ -369,6 +369,51 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       expect.stringContaining('provider exploded'),
     );
   });
+
+  // #490 reactive branch: a provider CONTEXT-OVERFLOW 400 in onError is classified,
+  // records a distinguishable cause, and stamps metadata.replayOverflow so the NEXT
+  // turn's budgeter trims aggressively (the recovery that un-bricks the chat).
+  it('#490: a context-overflow 400 stamps replayOverflow on the finalized row', async () => {
+    jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined as never);
+    jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined as never);
+    const { capturedOpts, aiChatMessageRepo } = await captureStreamCallbacks();
+
+    const overflow = Object.assign(new Error('too large'), {
+      statusCode: 400,
+      message:
+        "This model's maximum context length is 128000 tokens. However, your messages resulted in 214000 tokens. Please reduce the length.",
+    });
+    await capturedOpts.onError({ error: overflow });
+
+    // The seed row exists (finalizeOwner is the owner-write path).
+    expect(aiChatMessageRepo.finalizeOwner).toHaveBeenCalled();
+    const calls = aiChatMessageRepo.finalizeOwner.mock.calls as any[][];
+    const patch = calls[calls.length - 1][2] as {
+      status: string;
+      metadata: Record<string, unknown>;
+    };
+    expect(patch.status).toBe('error');
+    expect(patch.metadata.replayOverflow).toBe(true);
+    expect(patch.metadata.error).toContain('контекстное окно');
+  });
+
+  it('#490: a non-overflow error does NOT stamp replayOverflow', async () => {
+    jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined as never);
+    const { capturedOpts, aiChatMessageRepo } = await captureStreamCallbacks();
+    await capturedOpts.onError({ error: new Error('network reset') });
+    const calls = aiChatMessageRepo.finalizeOwner.mock.calls as any[][];
+    const patch = calls[calls.length - 1][2] as {
+      status: string;
+      metadata: Record<string, unknown>;
+    };
+    expect('replayOverflow' in patch.metadata).toBe(false);
+  });
 });
 
 /**

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

@@ -13,6 +13,7 @@ import {
   compactToolOutput,
   assistantParts,
   serializeSteps,
+  type StepPartsCache,
   rowToUiMessage,
   prepareAgentStep,
   stepBudgetWarning,
@@ -28,10 +29,14 @@ import {
   FINAL_STEP_NUDGE,
   STEP_LIMIT_NO_ANSWER_MARKER,
   OUTPUT_DEGENERATION_ERROR,
+  lastAssistantContextTokens,
+  lastAssistantReplayOverflow,
+  seedActivatedTools,
 } from './ai-chat.service';
 import type { AiChatMessage, Workspace } from '@docmost/db/types/entity.types';
 import { buildSystemPrompt } from './ai-chat.prompt';
 import type { McpClientsService } from './external-mcp/mcp-clients.service';
+import { resolveEffectiveReplayThreshold } from './history-budget';
 
 /**
  * Unit tests for compactToolOutput: the pure helper that shrinks tool outputs
@@ -114,6 +119,54 @@ describe('compactToolOutput', () => {
 describe('assistantParts', () => {
   type AnyPart = Record<string, unknown>;
 
+  // #490 memoization: assistantParts builds each step's parts once and caches
+  // them by the step OBJECT's identity, so a mid-stream flush does not
+  // re-stringify every prior step's (large) output. Observable property: with a
+  // shared cache, the second call over the SAME step object returns the cached
+  // (identical) part array even if the step's underlying output was swapped —
+  // proving the work was memoized, not redone.
+  it('memoizes a step by identity (shared cache => one build per step)', () => {
+    const cache: StepPartsCache = new WeakMap();
+    const step = {
+      text: 'x',
+      toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+      toolResults: [{ toolCallId: 'c1', toolName: 'getPage', output: { v: 1 } }],
+    };
+    const first = assistantParts([step], '', cache) as AnyPart[];
+    expect((first.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      1,
+    );
+    // Swap the output for a NEW value; a re-build would pick it up, a cache hit
+    // keeps the first result.
+    step.toolResults[0] = {
+      toolCallId: 'c1',
+      toolName: 'getPage',
+      output: { v: 2 },
+    };
+    const second = assistantParts([step], '', cache) as AnyPart[];
+    expect((second.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      1,
+    );
+    // Same cached part objects are reused.
+    expect(second.find((p) => p.type === 'tool-getPage')).toBe(
+      first.find((p) => p.type === 'tool-getPage'),
+    );
+  });
+
+  it('without a cache, each call rebuilds (no stale memo)', () => {
+    const step = {
+      text: 'x',
+      toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+      toolResults: [{ toolCallId: 'c1', toolName: 'getPage', output: { v: 1 } }],
+    };
+    const first = assistantParts([step], '') as AnyPart[];
+    step.toolResults[0].output = { v: 2 };
+    const second = assistantParts([step], '') as AnyPart[];
+    expect((second.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      2,
+    );
+  });
+
   it('emits output-available for a tool-call WITH a paired result', () => {
     const steps = [
       {
@@ -231,61 +284,320 @@ describe('assistantParts', () => {
   });
 });
 
-describe('serializeSteps', () => {
+// #490 trace format v2: per call the trace stores { input } for the call and an
+// OUTCOME element — { ok: true } on success, { error, kind: 'thrown' } on a
+// thrown tool-error, { error, kind: 'interrupted' } on a mid-step abort. The tool
+// OUTPUT is no longer duplicated here (it lives once in metadata.parts).
+describe('serializeSteps (trace v2)', () => {
   it('returns null when there are no calls or results', () => {
     expect(serializeSteps([])).toBeNull();
   });
 
-  it('flattens calls and results into a compact trace', () => {
+  it('pairs a successful call with an { ok: true } outcome and NO output', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'getPage', input: { id: 'p1' } }],
-        toolResults: [{ toolName: 'getPage', output: { title: 'T' } }],
+        toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: { id: 'p1' } }],
+        toolResults: [{ toolCallId: 'c1', toolName: 'getPage' }],
       },
     ]) as Array<Record<string, unknown>>;
     expect(trace).toHaveLength(2);
     expect(trace[0]).toEqual({ toolName: 'getPage', input: { id: 'p1' } });
-    expect(trace[1]).toEqual({ toolName: 'getPage', output: { title: 'T' } });
+    expect(trace[1]).toEqual({ toolName: 'getPage', ok: true });
+    // The output is NOT stored in the trace any more (dedup: it lives in parts).
+    expect(trace.some((e) => 'output' in e)).toBe(false);
   });
 
-  it('records a THROWN tool failure (tool-error part) with its error message', () => {
+  it('records a THROWN failure with { error, kind: "thrown" }', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'editPageText', input: { id: 'p1' } }],
+        toolCalls: [
+          { toolCallId: 'c1', toolName: 'editPageText', input: { id: 'p1' } },
+        ],
         toolResults: [],
         content: [
           {
             type: 'tool-error',
+            toolCallId: 'c1',
             toolName: 'editPageText',
             error: new Error('page is locked'),
           },
         ],
       },
     ]) as Array<Record<string, unknown>>;
-    // The call element is followed by a paired error element (mirroring how a
-    // successful result is appended), so the failure survives in the trace.
     expect(trace).toHaveLength(2);
     expect(trace[0]).toEqual({ toolName: 'editPageText', input: { id: 'p1' } });
     expect(trace[1]).toEqual({
       toolName: 'editPageText',
       error: 'page is locked',
+      kind: 'thrown',
     });
   });
 
-  it('truncates a very long tool-error message to the tool-output limit', () => {
+  it('marks an interrupted call (no result, no throw) with kind "interrupted"', () => {
+    const trace = serializeSteps([
+      {
+        toolCalls: [
+          { toolCallId: 'c1', toolName: 'createComment', input: { x: 1 } },
+        ],
+        toolResults: [],
+        content: [],
+      },
+    ]) as Array<Record<string, unknown>>;
+    expect(trace).toHaveLength(2);
+    expect(trace[1]).toEqual({
+      toolName: 'createComment',
+      error: 'Tool call did not complete.',
+      kind: 'interrupted',
+    });
+    // Structurally distinct from a thrown hard-fail so it never inflates an
+    // error-rate scan.
+    expect((trace[1] as { kind: string }).kind).not.toBe('thrown');
+  });
+
+  it('truncates a very long thrown-error message to the tool-output limit', () => {
     const long = 'x'.repeat(5000);
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'editPageText', input: {} }],
+        toolCalls: [{ toolCallId: 'c1', toolName: 'editPageText', input: {} }],
         toolResults: [],
-        content: [{ type: 'tool-error', toolName: 'editPageText', error: long }],
+        content: [
+          {
+            type: 'tool-error',
+            toolCallId: 'c1',
+            toolName: 'editPageText',
+            error: long,
+          },
+        ],
       },
     ]) as Array<Record<string, unknown>>;
     const errorText = trace[1].error as string;
-    // Truncated (not the full 5000 chars) and carries the omission marker.
     expect(errorText.length).toBeLessThan(long.length);
     expect(errorText).toContain('chars omitted');
   });
+
+  it('pairs parallel calls in one step with their outcomes by id', () => {
+    const trace = serializeSteps([
+      {
+        toolCalls: [
+          { toolCallId: 'a', toolName: 'getPage', input: {} },
+          { toolCallId: 'b', toolName: 'searchPages', input: {} },
+        ],
+        toolResults: [{ toolCallId: 'b', toolName: 'searchPages' }],
+        content: [
+          { type: 'tool-error', toolCallId: 'a', toolName: 'getPage', error: 'nope' },
+        ],
+      },
+    ]) as Array<Record<string, unknown>>;
+    // call a, outcome a (thrown), call b, outcome b (ok)
+    expect(trace).toHaveLength(4);
+    expect(trace[1]).toEqual({ toolName: 'getPage', error: 'nope', kind: 'thrown' });
+    expect(trace[3]).toEqual({ toolName: 'searchPages', ok: true });
+  });
+});
+
+// #490: every assistant row flushAssistant writes carries the v2 era marker so a
+// dual-shape diagnostic query can branch on the trace shape without inspecting it.
+describe('toolTraceVersion era marker (#490)', () => {
+  it('stamps metadata.toolTraceVersion = 2 on every flushed row', () => {
+    const seed = flushAssistant([], '', 'streaming');
+    expect(seed.metadata.toolTraceVersion).toBe(2);
+    const done = flushAssistant(
+      [
+        {
+          text: 'ok',
+          toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+          toolResults: [{ toolCallId: 'c1', toolName: 'getPage' }],
+        },
+      ],
+      '',
+      'completed',
+      { finishReason: 'stop' },
+    );
+    expect(done.metadata.toolTraceVersion).toBe(2);
+  });
+});
+
+// #490 replay-budget signal helpers over persisted history.
+describe('lastAssistantContextTokens', () => {
+  const row = (
+    role: string,
+    metadata: Record<string, unknown> | null,
+  ): AiChatMessage => ({ role, metadata }) as unknown as AiChatMessage;
+
+  it('reads the most recent assistant turn contextTokens (provider fact)', () => {
+    const hist = [
+      row('user', null),
+      row('assistant', { contextTokens: 12000 }),
+      row('user', null),
+      row('assistant', { contextTokens: 41000 }),
+    ];
+    expect(lastAssistantContextTokens(hist)).toBe(41000);
+  });
+
+  it('returns undefined when the last assistant turn recorded no usage', () => {
+    const hist = [row('assistant', { error: 'boom' }), row('user', null)];
+    expect(lastAssistantContextTokens(hist)).toBeUndefined();
+    expect(lastAssistantContextTokens([])).toBeUndefined();
+  });
+});
+
+// #490 snapshotOpenPage fast-path: skip the full Markdown export + upsert when a
+// snapshot already exists at the page's CURRENT version (same updated_at instant).
+describe('snapshotOpenPage fast-path (#490)', () => {
+  function makeSvc(existingSnapshot: unknown, pageUpdatedAt: Date) {
+    const exportPageMarkdown = jest.fn(async () => '# md');
+    const upsert = jest.fn(async () => undefined);
+    const findByChatPage = jest.fn(async () => existingSnapshot);
+    const pageRepo = {
+      findById: jest.fn(async () => ({
+        id: 'p1',
+        workspaceId: 'ws1',
+        updatedAt: pageUpdatedAt,
+      })),
+    };
+    const svc = new AiChatService(
+      {} as never, // ai
+      {} as never, // aiChatRepo
+      {} as never, // aiChatMessageRepo
+      { findByChatPage, upsert } as never, // aiChatPageSnapshotRepo
+      {} as never, // aiSettings
+      { exportPageMarkdown } as never, // tools
+      {} as never, // mcpClients
+      {} as never, // aiAgentRoleRepo
+      pageRepo as never, // pageRepo
+      {} as never, // pageAccess
+      {} as never, // environment
+    );
+    return { svc, exportPageMarkdown, upsert, findByChatPage };
+  }
+
+  const args = () =>
+    [
+      'chat1',
+      'p1',
+      { id: 'ws1' } as never,
+      { id: 'u1' } as never,
+      'sess',
+    ] as const;
+
+  it('skips export + upsert when the snapshot is already at this page version', async () => {
+    const t = new Date('2026-07-07T10:00:00Z');
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      { pageUpdatedAt: t, contentMd: '# md' },
+      t,
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).not.toHaveBeenCalled();
+    expect(upsert).not.toHaveBeenCalled();
+  });
+
+  it('exports + upserts when the page advanced since the snapshot', async () => {
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      { pageUpdatedAt: new Date('2026-07-07T10:00:00Z'), contentMd: 'old' },
+      new Date('2026-07-07T11:00:00Z'),
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).toHaveBeenCalledTimes(1);
+    expect(upsert).toHaveBeenCalledTimes(1);
+  });
+
+  it('seeds (exports + upserts) on the first turn (no snapshot yet)', async () => {
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      undefined,
+      new Date('2026-07-07T10:00:00Z'),
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).toHaveBeenCalledTimes(1);
+    expect(upsert).toHaveBeenCalledTimes(1);
+  });
+});
+
+// #490 deferred-tool activation persisted across turns.
+describe('seedActivatedTools', () => {
+  const valid = new Set(['Search_web', 'getPageJson', 'diffPageVersions']);
+
+  it('seeds from persisted metadata, intersected with current valid names', () => {
+    expect(
+      seedActivatedTools(
+        { activatedTools: ['Search_web', 'getPageJson'] },
+        valid,
+      ),
+    ).toEqual(['Search_web', 'getPageJson']);
+  });
+
+  it('drops a stored tool that is no longer valid (allowlist/role changed)', () => {
+    // 'Habr_publish' was activated before but is not in the current allowlist.
+    expect(
+      seedActivatedTools({ activatedTools: ['Search_web', 'Habr_publish'] }, valid),
+    ).toEqual(['Search_web']);
+  });
+
+  it('is empty/robust for missing, non-array, or unknown-shaped metadata', () => {
+    expect(seedActivatedTools(undefined, valid)).toEqual([]);
+    expect(seedActivatedTools({}, valid)).toEqual([]);
+    expect(seedActivatedTools({ activatedTools: 'nope' }, valid)).toEqual([]);
+    expect(
+      seedActivatedTools({ activatedTools: [1, 'getPageJson', null] }, valid),
+    ).toEqual(['getPageJson']);
+  });
+
+  it('de-duplicates stored names', () => {
+    expect(
+      seedActivatedTools(
+        { activatedTools: ['getPageJson', 'getPageJson'] },
+        valid,
+      ),
+    ).toEqual(['getPageJson']);
+  });
+});
+
+describe('lastAssistantReplayOverflow', () => {
+  const row = (
+    role: string,
+    metadata: Record<string, unknown> | null,
+  ): AiChatMessage => ({ role, metadata }) as unknown as AiChatMessage;
+
+  it('is true only when the LAST assistant turn overflowed', () => {
+    expect(
+      lastAssistantReplayOverflow([
+        row('assistant', { replayOverflow: true }),
+        row('user', null),
+      ]),
+    ).toBe(true);
+    // A recovered (later, non-overflow) assistant turn clears it.
+    expect(
+      lastAssistantReplayOverflow([
+        row('assistant', { replayOverflow: true }),
+        row('user', null),
+        row('assistant', { contextTokens: 5 }),
+      ]),
+    ).toBe(false);
+    expect(lastAssistantReplayOverflow([])).toBe(false);
+  });
+
+  // #490 reactive recovery: a prior turn stamped `replayOverflow` must make the
+  // NEXT turn's effective budget the AGGRESSIVE 0.5x cut — that harder trim is
+  // what un-bricks a chat that just 400'd on the context window. This exercises
+  // the exact wiring the service uses: read the stamp, then scale the threshold.
+  it('#490: a prior replayOverflow drives the next turn to the 0.5x aggressive budget', () => {
+    const history = [
+      row('assistant', { replayOverflow: true }),
+      row('user', null),
+    ];
+    const priorOverflowed = lastAssistantReplayOverflow(history);
+    expect(priorOverflowed).toBe(true);
+    // Base budget 100k -> aggressive recovery halves it to 50k this turn.
+    expect(resolveEffectiveReplayThreshold(100_000, priorOverflowed)).toBe(50_000);
+    // Odd base floors, not rounds.
+    expect(resolveEffectiveReplayThreshold(99_999, true)).toBe(49_999);
+    // No prior overflow -> the base budget is used verbatim (no aggressive cut).
+    expect(resolveEffectiveReplayThreshold(100_000, false)).toBe(100_000);
+    // An explicit off-switch (null) is never overridden, even on recovery.
+    expect(resolveEffectiveReplayThreshold(null, true)).toBeNull();
+  });
 });
 
 describe('rowToUiMessage', () => {
@@ -618,6 +930,23 @@ describe('flushAssistant', () => {
     expect(flushed.metadata.error).toBe('boom');
   });
 
+  // #490 observability: the replay budgeter's decision is stamped on the turn.
+  it('records replayTrimmedToTokens + replayOverflow when provided', () => {
+    const f = flushAssistant([], '', 'error', {
+      error: 'ctx',
+      replayTrimmedToTokens: 42_000,
+      replayOverflow: true,
+    });
+    expect(f.metadata.replayTrimmedToTokens).toBe(42_000);
+    expect(f.metadata.replayOverflow).toBe(true);
+  });
+
+  it('omits the replay metadata when not provided', () => {
+    const f = flushAssistant([], '', 'completed', { finishReason: 'stop' });
+    expect('replayTrimmedToTokens' in f.metadata).toBe(false);
+    expect('replayOverflow' in f.metadata).toBe(false);
+  });
+
   // #274 observability: the page-change diff the agent saw this turn is persisted
   // to metadata.pageChanged when a non-empty diff was injected, and omitted when
   // the diff is empty/whitespace or the arg is not supplied.

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

@@ -55,6 +55,12 @@ import {
   type SelectionContext,
 } from './tools/current-page.util';
 import { roleModelOverride } from './roles/role-model-config';
+import {
+  resolveReplayBudget,
+  resolveEffectiveReplayThreshold,
+  isContextOverflowError,
+  trimHistoryForReplay,
+} from './history-budget';
 import {
   startSseHeartbeat,
   stripStreamingHopByHopHeaders,
@@ -127,6 +133,15 @@ const STEP_LIMIT_NO_ANSWER_MARKER =
 const OUTPUT_DEGENERATION_ERROR =
   'Output degeneration detected (repeated token loop)';
 
+// Prefix recorded on the assistant row when the provider rejected the turn for
+// CONTEXT OVERFLOW (#490): the replayed history exceeded the model's window. The
+// row is ALSO stamped `metadata.replayOverflow` so the NEXT turn's budgeter trims
+// aggressively (the reactive recovery — the overflowing turn had no usage signal
+// to trigger preventive trimming, so the classified 400 is what un-bricks it).
+export const CONTEXT_OVERFLOW_ERROR_PREFIX =
+  'Диалог превысил контекстное окно модели; история будет агрессивно ' +
+  'сокращена на следующем ходу.';
+
 /**
  * Compute the step-budget warning text (#444), or '' when this step is outside
  * the warning band. The warning fires on steps
@@ -882,6 +897,21 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const freshPage = await this.pageRepo.findById(pageId);
       // Page deleted during the turn (or somehow foreign) => don't write.
       if (!freshPage || freshPage.workspaceId !== workspace.id) return;
+      // Fast-path (#490): if a snapshot already exists at THIS page version
+      // (same updated_at instant), its content is already current — skip the full
+      // Markdown export + upsert entirely. A turn that did NOT touch the open page
+      // (the common case) thus does no snapshot work. This mirrors the read-side
+      // fast path in detectPageChange (sameInstant): both trust that a page edit
+      // bumps updated_at. When the agent (or a human) DID edit the page this turn,
+      // updated_at advanced, so this does not match and we re-export as before.
+      const existing = await this.aiChatPageSnapshotRepo.findByChatPage(
+        chatId,
+        pageId,
+        workspace.id,
+      );
+      if (existing && sameInstant(existing.pageUpdatedAt, freshPage.updatedAt)) {
+        return;
+      }
       const currentMd = await this.tools.exportPageMarkdown(
         user,
         sessionId,
@@ -921,10 +951,17 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
     // supplied or the supplied one does not belong to this workspace.
     let isNewChat = false;
     let chatId = body.chatId;
+    // Persisted chat-level metadata bag (#490): read once here so the deferred-tool
+    // activation set can be seeded from the previous turn. Undefined for a new chat.
+    let chatMetadata: Record<string, unknown> | undefined;
     if (chatId) {
       const existing = await this.aiChatRepo.findById(chatId, workspace.id);
       if (!existing) {
         chatId = undefined;
+      } else {
+        chatMetadata = (existing.metadata ?? undefined) as
+          | Record<string, unknown>
+          | undefined;
       }
     }
     // The open page the client sent is attacker-controllable — BOTH its id and
@@ -1086,7 +1123,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // per-row conversion and degraded to plain text with a "[tool context
       // omitted]" marker rather than 500-ing the whole turn (silent loss of tool
       // context is not acceptable — the model must see the truncation).
-      const messages = await convertHistoryResilient(uiMessages, (index, err) =>
+      let messages = await convertHistoryResilient(uiMessages, (index, err) =>
         this.logger.warn(
           `Degraded unconvertible history row ${index} on chat ${chatId} to text: ${
             err instanceof Error ? err.message : 'unknown error'
@@ -1135,6 +1172,56 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // Here we only need the admin-configured system prompt.
       const resolved = await this.aiSettings.resolve(workspace.id);
 
+      // History-replay token budget (#490). The full conversation is replayed to
+      // the provider every turn, so a long chat eventually 400s on the context
+      // window — forever. Bound the REPLAYED history (never the persisted rows).
+      // PRIMARY signal is the provider's own fact: the last turn's contextTokens.
+      const replayBudget = resolveReplayBudget(resolved?.chatContextWindowRaw);
+      if (replayBudget.usedDefault) {
+        // The default fires precisely for installs with NO configured window —
+        // the ones that hit terminal overflow. Warn so it is observable.
+        this.logger.warn(
+          `AI chat (chat ${chatId}): no chatContextWindow configured; ` +
+            `applying the default replay budget (${replayBudget.thresholdTokens} tokens).`,
+        );
+      }
+      // Last turn's provider-reported context size (authoritative when present).
+      const priorContextTokens = lastAssistantContextTokens(oldHistory);
+      // Reactive recovery (#490): if the LAST turn was rejected for context
+      // overflow (stamped by onError), trim AGGRESSIVELY this turn — the
+      // overflowing turn produced no usage signal, so a normal-threshold trim may
+      // not shrink enough to fit. This is what un-bricks a chat that just 400'd.
+      const priorOverflowed = lastAssistantReplayOverflow(oldHistory);
+      const effectiveThreshold = resolveEffectiveReplayThreshold(
+        replayBudget.thresholdTokens,
+        priorOverflowed,
+      );
+      if (priorOverflowed) {
+        this.logger.warn(
+          `AI chat (chat ${chatId}): previous turn hit context overflow; ` +
+            `applying aggressive replay budget (${effectiveThreshold} tokens).`,
+        );
+      }
+      const preTrim = trimHistoryForReplay(
+        messages,
+        effectiveThreshold,
+        // A prior OVERFLOW means the provider count is stale/absent — force the
+        // char-estimate path by ignoring priorContextTokens on recovery.
+        priorOverflowed ? undefined : priorContextTokens,
+      );
+      messages = preTrim.messages;
+      // Observability (#490): record the budgeter's decision on the turn so the UI
+      // can surface "replay truncated at N tokens". Threaded into flushAssistant.
+      let replayTrimmedToTokens: number | undefined = preTrim.trimmed
+        ? preTrim.estimatedTokens
+        : undefined;
+      if (preTrim.trimmed) {
+        this.logger.log(
+          `AI chat (chat ${chatId}): replay history trimmed to ~${preTrim.estimatedTokens} ` +
+            `tokens (budget ${replayBudget.thresholdTokens}).`,
+        );
+      }
+
       // Build the external MCP toolset FIRST so the system prompt can carry each
       // connected server's admin-authored guidance (#180). Merge in admin-
       // configured external MCP tools (web search, etc.; §6.8). A down/slow
@@ -1326,10 +1413,19 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       //    tools + ALL external MCP tools), computed from the ACTUAL toolset so an
       //    external tool is loadable by its namespaced name. loadTools rejects any
       //    name outside this set.
-      const activatedTools = new Set<string>();
       const validDeferredNames = new Set<string>(
         Object.keys(baseTools).filter((k) => !CORE_TOOL_SET.has(k)),
       );
+      // #490: seed the activation set from the chat's PERSISTED set so the model
+      // does not re-run loadTools every turn to re-activate the same tools. Only
+      // when deferred loading is enabled, and ALWAYS intersected with the CURRENT
+      // valid deferred names — an allowlist/role change must never resurrect a tool
+      // that no longer exists (prepareAgentStep would get a phantom active name).
+      const activatedTools = new Set<string>(
+        deferredEnabled
+          ? seedActivatedTools(chatMetadata, validDeferredNames)
+          : [],
+      );
       // Add the loadTools meta-tool ONLY when the feature is enabled; when off the
       // toolset and behavior are exactly as before.
       const tools = deferredEnabled
@@ -1339,6 +1435,39 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
           }
         : baseTools;
 
+      // #490: persist the (deterministically ordered) activation set back onto the
+      // chat metadata at turn end, so the NEXT turn seeds from it. Once-guarded and
+      // skipped when nothing new was activated (the set equals its seed) so an
+      // ordinary turn adds no extra write. Preserves other metadata keys.
+      let activatedToolsPersisted = false;
+      const persistActivatedTools = async (): Promise<void> => {
+        if (!deferredEnabled || activatedToolsPersisted || !chatId) return;
+        activatedToolsPersisted = true;
+        const current = [...activatedTools].sort();
+        const seeded = seedActivatedTools(chatMetadata, validDeferredNames).sort();
+        if (current.length === 0 || current.join('') === seeded.join('')) {
+          return; // nothing new activated -> no write
+        }
+        try {
+          await this.aiChatRepo.update(
+            chatId,
+            {
+              metadata: {
+                ...(chatMetadata ?? {}),
+                activatedTools: current,
+              },
+            } as never,
+            workspace.id,
+          );
+        } catch (err) {
+          this.logger.warn(
+            `Failed to persist activated tools (chat ${chatId}): ${
+              err instanceof Error ? err.message : 'unknown error'
+            }`,
+          );
+        }
+      };
+
       // Accumulate the turn's streamed output so a provider error / disconnect can
       // persist the PARTIAL answer the user already saw — the SDK's onError/onAbort
       // callbacks don't hand us the in-progress text. `capturedSteps` holds finished
@@ -1347,6 +1476,11 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const capturedSteps: StepLike[] = [];
       let inProgressText = '';
 
+      // Per-turn step->parts memo (#490): shared across every flushAssistant call
+      // this turn so each finished step's (large) output is JSON-stringified ONCE,
+      // not re-stringified on every subsequent onStepFinish flush (was O(N²)).
+      const partsCache: StepPartsCache = new WeakMap();
+
       // Token-degeneration guard (#444). When the final-step lockdown is OFF, a
       // runaway repetition loop (the 255KB "loadTools." incident) is aborted via
       // this internal controller, unioned with the run/socket signal below. The
@@ -1404,27 +1538,39 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // Per-step (non-terminal) update: persist the finished steps the moment a
       // step ends. Tolerant — a failed update is logged and swallowed so it never
       // throws into the stream. Keeps status 'streaming'.
-      const updateStreaming = async (): Promise<void> => {
-        if (!assistantId) return;
+      //
+      // #491: it now SIGNALS its outcome — the persisted `stepsPersisted` count on
+      // a CONFIRMED write, or null when it was skipped/failed. The caller rotates
+      // the run-stream registry ring ONLY on a non-null return (a confirmed
+      // persist), so a failed persist never rotates away a step nobody has (the
+      // classic inversion bug); a failure just makes the ring cover more.
+      const updateStreaming = async (): Promise<number | null> => {
+        if (!assistantId) return null;
         // Cheap short-circuit once the turn is finalized (see `finalized` below).
         // The AUTHORITATIVE guard is `onlyIfStreaming` on the UPDATE: a late
         // fire-and-forget step update could still be in flight on another pool
         // connection when finalize runs, so the SQL `WHERE status='streaming'`
         // (not this flag) is what prevents it clobbering the terminal row.
-        if (finalized) return;
+        if (finalized) return null;
+        // Build the flush ONCE so the returned count is EXACTLY the persisted
+        // `stepsPersisted` (both derive from capturedSteps.length at this instant).
+        const flushed = flushAssistant(capturedSteps, '', 'streaming', {
+          pageChanged,
+          partsCache,
+        });
+        const stepsPersisted = flushed.metadata.stepsPersisted as number;
         try {
-          await this.aiChatMessageRepo.update(
-            assistantId,
-            workspace.id,
-            flushAssistant(capturedSteps, '', 'streaming', { pageChanged }),
-            { onlyIfStreaming: true },
-          );
+          await this.aiChatMessageRepo.update(assistantId, workspace.id, flushed, {
+            onlyIfStreaming: true,
+          });
+          return stepsPersisted;
         } catch (err) {
           this.logger.warn(
             `Failed to update streaming assistant row: ${
               err instanceof Error ? err.message : 'unknown error'
             }`,
           );
+          return null;
         }
       };
 
@@ -1593,7 +1739,24 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // this point still recovers the step. Not awaited here (never block the
             // stream), but SERIALIZED via stepUpdateChain so the writes commit in
             // step order; updateStreaming is error-tolerant (logs + swallows).
-            stepUpdateChain = stepUpdateChain.then(() => updateStreaming());
+            // #491: on a CONFIRMED persist, rotate the run-stream registry ring to
+            // drop the now-on-disk steps (stamp < stepsPersisted). Gated on the
+            // resumable flag (same as open/bind) and identity-checked in the
+            // registry; a null return (skipped/failed) rotates NOTHING (auto-safe).
+            stepUpdateChain = stepUpdateChain.then(async () => {
+              const persisted = await updateStreaming();
+              if (
+                persisted != null &&
+                runId &&
+                this.environment?.isAiChatResumableStreamEnabled?.()
+              ) {
+                this.streamRegistry?.confirmPersistedStep(
+                  chatId,
+                  runId,
+                  persisted,
+                );
+              }
+            });
             // #184: persist the run's progress (finished-step count). Fire-and-
             // forget; the hook swallows its own errors.
             if (runId) runHooks?.onStep?.(runId, capturedSteps.length);
@@ -1649,6 +1812,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 // closure scope here). Omitted/0 = no limit.
                 maxContextTokens: resolved?.chatContextWindow,
                 pageChanged,
+                partsCache,
+                replayTrimmedToTokens,
               }),
             );
             // #184/#487: the RUN is finalized ALWAYS (never gated on the message).
@@ -1673,6 +1838,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // own edits are baked in — and this also SEEDS the snapshot on the first
             // turn. Runs once across every terminal path (see snapshotTurnEnd).
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
 
             // Generate the chat title for a freshly created chat AFTER the stream's
             // provider call has completed — NOT concurrently with it. The z.ai coding
@@ -1696,7 +1863,16 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // object, so the actual provider cause is clearly logged. Reuse the
             // shared formatter so provider error formatting stays unified.
             const e = error as { stack?: string };
-            const errorText = describeProviderError(error, String(error));
+            // #490 reactive branch: classify a CONTEXT-OVERFLOW rejection (the
+            // replayed history exceeded the model window). The overflowing turn had
+            // no prior usage to trigger preventive trimming, so we record a clear,
+            // distinguishable cause AND stamp the row so the NEXT turn's budgeter
+            // trims aggressively — the reactive recovery that un-bricks the chat.
+            const overflow = isContextOverflowError(error);
+            const providerError = describeProviderError(error, String(error));
+            const errorText = overflow
+              ? `${CONTEXT_OVERFLOW_ERROR_PREFIX} (${providerError})`
+              : providerError;
             this.logger.error(`AI chat stream error: ${errorText}`, e?.stack);
             // DIAGNOSTIC (Safari stream-drop investigation) — temporary: timing of
             // an error-terminated stream.
@@ -1714,6 +1890,9 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
               flushAssistant(capturedSteps, inProgressText, 'error', {
                 error: errorText,
                 pageChanged,
+                partsCache,
+                replayTrimmedToTokens,
+                replayOverflow: overflow || undefined,
               }),
             );
             // #184: settle the RUN as failed, carrying the provider/transport cause.
@@ -1723,6 +1902,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // committed before the error must be baked into the snapshot, or the
             // next turn would mis-report it as a user edit.
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
           },
           onAbort: async ({ steps }) => {
             // #444: distinguish a degeneration abort (our internal controller) from
@@ -1737,6 +1918,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 flushAssistant(capturedSteps, truncated, 'error', {
                   error: OUTPUT_DEGENERATION_ERROR,
                   pageChanged,
+                  partsCache,
                 }),
               );
               if (runId)
@@ -1747,6 +1929,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 );
               await closeExternalClients();
               await snapshotTurnEnd();
+              // #490: persist the deferred-tool activation set for the next turn.
+              await persistActivatedTools();
               return;
             }
             const partialChars =
@@ -1771,6 +1955,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             await finalizeAssistant(
               flushAssistant(capturedSteps, inProgressText, 'aborted', {
                 pageChanged,
+                partsCache,
               }),
             );
             // #184: settle the RUN as aborted (an explicit user stop reached the
@@ -1781,6 +1966,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // committed before the client disconnect / stop() must be baked into the
             // snapshot, or the next turn would mis-report it as a user edit.
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
           },
         });
 
@@ -2091,6 +2278,70 @@ export function chatStreamMetadata(
   return undefined;
 }
 
+/**
+ * The provider-reported context size of the most recent assistant turn, read from
+ * its persisted `metadata.contextTokens` (#490 replay budgeter's PRIMARY signal —
+ * the provider's own fact, not an estimate). Returns undefined for a chat with no
+ * assistant turn yet, or one whose last turn recorded no usage (e.g. it errored),
+ * in which case the budgeter falls back to the char-estimate.
+ */
+export function lastAssistantContextTokens(
+  history: ReadonlyArray<AiChatMessage>,
+): number | undefined {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const row = history[i];
+    if (row.role !== 'assistant') continue;
+    const meta = (row.metadata ?? {}) as { contextTokens?: unknown };
+    const n = meta.contextTokens;
+    return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Seed the per-turn deferred-tool activation set from a chat's persisted metadata
+ * (#490), INTERSECTED with the current valid deferred names. Persisting the set
+ * across turns saves the model re-running loadTools every turn to re-activate the
+ * same tools; intersecting on load means a changed allowlist / role can never
+ * resurrect a tool that no longer exists (which would hand prepareAgentStep a
+ * phantom active name). Tolerant of any stored shape — a non-array is ignored.
+ */
+export function seedActivatedTools(
+  metadata: Record<string, unknown> | undefined,
+  validDeferredNames: ReadonlySet<string>,
+): string[] {
+  const stored = metadata?.activatedTools;
+  if (!Array.isArray(stored)) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const name of stored) {
+    if (typeof name === 'string' && validDeferredNames.has(name) && !seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether the most recent assistant turn was rejected for CONTEXT OVERFLOW
+ * (#490): its row carries `metadata.replayOverflow` (stamped by the stream's
+ * onError). The next turn's budgeter reads this to trim aggressively — the
+ * reactive recovery. Only the LAST assistant turn matters (an older overflow was
+ * already recovered), so we stop at the first assistant row scanning backwards.
+ */
+export function lastAssistantReplayOverflow(
+  history: ReadonlyArray<AiChatMessage>,
+): boolean {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const row = history[i];
+    if (row.role !== 'assistant') continue;
+    const meta = (row.metadata ?? {}) as { replayOverflow?: unknown };
+    return meta.replayOverflow === true;
+  }
+  return false;
+}
+
 /** The last message with role 'user' from a useChat payload, if any. */
 function lastUserMessage(
   messages: UIMessage[] | undefined,
@@ -2152,6 +2403,15 @@ export function sanitizeUserParts(
 /** Marker for a history row whose tool parts could not be replayed (#489). */
 export const TOOL_CONTEXT_OMITTED_MARKER = '[tool context omitted]';
 
+/**
+ * Synthetic error text for a tool call that neither returned a result nor threw
+ * a `tool-error` — i.e. it was interrupted mid-step (an abort / server restart).
+ * Shared by `assistantParts` (the replayed `output-error` part) and
+ * `serializeSteps` (the `{ kind: 'interrupted' }` trace element) so the replay
+ * text and the trace stay in lockstep (#490).
+ */
+export const TOOL_CALL_INCOMPLETE_TEXT = 'Tool call did not complete.';
+
 /**
  * Convert persisted UI history to model messages, tolerating a single poisoned
  * row (#489). `convertToModelMessages` over the WHOLE array throws if ANY row is
@@ -2359,71 +2619,97 @@ function normalizeToolError(error: unknown): string {
  */
 // Exported only so the unit tests can import these pure helpers; exporting
 // them does not change runtime behavior.
+/**
+ * Per-turn memo for {@link assistantParts}: a step's rebuilt parts keyed by the
+ * step OBJECT's identity (#490). A finished step in `capturedSteps` keeps a stable
+ * reference across every mid-stream flush, and `compactToolOutput` inside it does a
+ * `JSON.stringify` of the whole (often 50–200 KB) output — so without a memo each
+ * `onStepFinish` re-stringifies EVERY prior step's output (O(N²) stringify over a
+ * turn). Keyed by step identity => one stringify per step per turn. WeakMap so a
+ * turn's steps are GC'd with the turn.
+ */
+export type StepPartsCache = WeakMap<object, Array<Record<string, unknown>>>;
+
+/** Build the parts for ONE step (text + a part per tool call). Pure. */
+function buildStepParts(step: StepLike): Array<Record<string, unknown>> {
+  const parts: Array<Record<string, unknown>> = [];
+  if (step.text) {
+    parts.push({ type: 'text', text: step.text });
+  }
+  // Index this step's results by tool call id to pair calls with outputs.
+  const resultsById = new Map<string, unknown>();
+  for (const r of step.toolResults ?? []) {
+    if (r.toolCallId) resultsById.set(r.toolCallId, r.output);
+  }
+  // Index this step's THROWN tool failures (ai@6 `tool-error` content parts)
+  // by tool call id, so a call that failed replays with its real error text.
+  const errorsById = new Map<string, unknown>();
+  for (const part of step.content ?? []) {
+    if (part.type === 'tool-error' && part.toolCallId) {
+      errorsById.set(part.toolCallId, part.error);
+    }
+  }
+  for (const call of step.toolCalls ?? []) {
+    if (!call.toolName || !call.toolCallId) continue;
+    const hasResult = resultsById.has(call.toolCallId);
+    if (hasResult) {
+      // output-available: the tool returned; the next turn replays its result.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-available',
+        input: call.input,
+        output: compactToolOutput(resultsById.get(call.toolCallId)),
+      });
+    } else if (errorsById.has(call.toolCallId)) {
+      // The tool THREW: replay the REAL error so the model on the next turn
+      // knows WHY the call failed (and does not blindly repeat it). An
+      // output-error round-trips through convertToModelMessages as a balanced
+      // tool-call + tool-result, keeping the rebuilt history valid.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-error',
+        input: call.input,
+        errorText: normalizeToolError(errorsById.get(call.toolCallId)),
+      });
+    } else {
+      // No paired result AND no tool-error (e.g. aborted mid-step). Persisting
+      // a bare tool-call (input-available) would replay as an unpaired call and
+      // throw MissingToolResultsError on the next turn (convertToModelMessages
+      // emits no tool-result for it). Emit a SYNTHETIC paired result instead:
+      // an output-error round-trips through convertToModelMessages as a
+      // balanced tool-call + tool-result, keeping the rebuilt history valid.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-error',
+        input: call.input,
+        errorText: TOOL_CALL_INCOMPLETE_TEXT,
+      });
+    }
+  }
+  return parts;
+}
+
 export function assistantParts(
   steps: ReadonlyArray<StepLike> | undefined,
   fallbackText: string,
+  cache?: StepPartsCache,
 ): UIMessage['parts'] {
   const parts: Array<Record<string, unknown>> = [];
-  let sawText = false;
   for (const step of steps ?? []) {
-    if (step.text) {
-      parts.push({ type: 'text', text: step.text });
-      sawText = true;
-    }
-    // Index this step's results by tool call id to pair calls with outputs.
-    const resultsById = new Map<string, unknown>();
-    for (const r of step.toolResults ?? []) {
-      if (r.toolCallId) resultsById.set(r.toolCallId, r.output);
-    }
-    // Index this step's THROWN tool failures (ai@6 `tool-error` content parts)
-    // by tool call id, so a call that failed replays with its real error text.
-    const errorsById = new Map<string, unknown>();
-    for (const part of step.content ?? []) {
-      if (part.type === 'tool-error' && part.toolCallId) {
-        errorsById.set(part.toolCallId, part.error);
-      }
-    }
-    for (const call of step.toolCalls ?? []) {
-      if (!call.toolName || !call.toolCallId) continue;
-      const hasResult = resultsById.has(call.toolCallId);
-      if (hasResult) {
-        // output-available: the tool returned; the next turn replays its result.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-available',
-          input: call.input,
-          output: compactToolOutput(resultsById.get(call.toolCallId)),
-        });
-      } else if (errorsById.has(call.toolCallId)) {
-        // The tool THREW: replay the REAL error so the model on the next turn
-        // knows WHY the call failed (and does not blindly repeat it). An
-        // output-error round-trips through convertToModelMessages as a balanced
-        // tool-call + tool-result, keeping the rebuilt history valid.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-error',
-          input: call.input,
-          errorText: normalizeToolError(errorsById.get(call.toolCallId)),
-        });
-      } else {
-        // No paired result AND no tool-error (e.g. aborted mid-step). Persisting
-        // a bare tool-call (input-available) would replay as an unpaired call and
-        // throw MissingToolResultsError on the next turn (convertToModelMessages
-        // emits no tool-result for it). Emit a SYNTHETIC paired result instead:
-        // an output-error round-trips through convertToModelMessages as a
-        // balanced tool-call + tool-result, keeping the rebuilt history valid.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-error',
-          input: call.input,
-          errorText: 'Tool call did not complete.',
-        });
-      }
+    // Memoize per step object (#490): a finished step is immutable and keeps its
+    // reference across flushes, so its parts (and the costly output stringify) are
+    // built exactly once per turn. A cache miss (or no cache) just rebuilds.
+    let stepParts = cache?.get(step as object);
+    if (!stepParts) {
+      stepParts = buildStepParts(step);
+      cache?.set(step as object, stepParts);
     }
+    parts.push(...stepParts);
   }
+  const sawText = parts.some((p) => p.type === 'text');
   if (!sawText && fallbackText) {
     // No per-step text (e.g. a single final block): append the final text after
     // any tool parts so the natural call -> result -> answer order is preserved.
@@ -2586,6 +2872,16 @@ export function flushAssistant(
     maxContextTokens?: number;
     error?: string;
     pageChanged?: { title: string; diff: string } | null;
+    // Per-turn step->parts memo (#490): pass the SAME cache on every flush of a
+    // turn so each finished step's output is stringified once, not once per flush.
+    partsCache?: StepPartsCache;
+    // #490 observability: when the replay budgeter trimmed this turn's history,
+    // the (estimated) token size it trimmed to — the UI can show "replay truncated
+    // at N tokens". Omitted when nothing was trimmed.
+    replayTrimmedToTokens?: number;
+    // #490 reactive branch: set when the provider rejected this turn for context
+    // overflow. Stamped into metadata so the NEXT turn's budgeter trims aggressively.
+    replayOverflow?: boolean;
   },
 ): AssistantFlush {
   const finished = capturedSteps ?? [];
@@ -2595,13 +2891,32 @@ export function flushAssistant(
   // in-progress step's text (the partial answer cut off by an error/abort, or
   // simply not yet flushed mid-stream) as the last text part so the persisted
   // parts match what streamed to the client.
-  const parts = assistantParts(finished, '') as unknown as Array<
-    Record<string, unknown>
-  >;
+  const parts = assistantParts(
+    finished,
+    '',
+    extra?.partsCache,
+  ) as unknown as Array<Record<string, unknown>>;
   if (trailing) parts.push({ type: 'text', text: trailing });
 
   const metadata: Record<string, unknown> = {
     parts: parts as unknown as UIMessage['parts'],
+    // Era marker for the `tool_calls` trace shape (#490): v2 stores outcome flags
+    // ({ ok } / { error, kind }) and NO tool output (the output lives once in
+    // `parts`). Old rows have no marker and the legacy { output } shape; a
+    // dual-shape query branches on this. Old rows are deliberately NOT migrated.
+    toolTraceVersion: 2,
+    // #491 STEP MARKER: the number of FINISHED steps whose parts are in THIS row,
+    // written by the SAME flush that builds `parts` (atomically — they are both
+    // derived from `finished`, so the marker can NEVER disagree with the persisted
+    // parts). This is the step-alignment anchor the resume stack builds on:
+    // - the registry rotates its retention ring only on a CONFIRMED persist of
+    //   step N (commit 3);
+    // - attach slices the tail at "step > N" from the client's persisted seed.
+    // It is NOT `run.stepCount`: recordStep is fire-and-forget and NOT atomic with
+    // the parts write, so stepCount could race ahead of the persisted parts
+    // (seed↔marker drift). The in-progress trailing text (an error/abort partial,
+    // or a mid-stream flush) is NOT a finished step and is excluded from the count.
+    stepsPersisted: finished.length,
   };
   // finishReason: prefer an explicit one; else derive a sensible value from the
   // terminal status (so onError/onAbort records keep their historical reason).
@@ -2617,6 +2932,9 @@ export function flushAssistant(
   if (extra?.contextTokens) metadata.contextTokens = extra.contextTokens;
   if (extra?.maxContextTokens)
     metadata.maxContextTokens = extra.maxContextTokens;
+  if (extra?.replayTrimmedToTokens)
+    metadata.replayTrimmedToTokens = extra.replayTrimmedToTokens;
+  if (extra?.replayOverflow) metadata.replayOverflow = true;
   if (extra?.error) metadata.error = extra.error;
   // Persist the page-change diff the agent saw this turn (#274 observability),
   // so history / the Markdown export can show what the user changed. Only when
@@ -2642,42 +2960,85 @@ export function flushAssistant(
 
 /**
  * Reduce SDK step objects to a compact, JSON-serializable trace for the
- * `tool_calls` column. Stores only what the UI action-log and history need —
- * never raw provider payloads or keys.
+ * `tool_calls` column — trace format **v2** (#490).
+ *
+ * v2 stores, per call, ONLY the metadata a queryable trace needs — never the
+ * tool OUTPUT. Before #490 each output was persisted TWICE: once here (compacted)
+ * and once in `metadata.parts` (via `assistantParts`), so a 50-step run with
+ * 50–200 KB outputs wrote hundreds of MB per turn (each `onStepFinish` rewrote
+ * the whole row). The parts copy is the one the model replays and the UI/Markdown
+ * export render, so the trace copy of the output was pure duplication. v2 keeps
+ * the output ONLY in parts and reduces the trace to outcome flags.
+ *
+ * Element shapes (paired per call, in order):
+ *  - `{ toolName, input }`                       — the call
+ *  - `{ toolName, ok: true }`                     — it returned a result (success)
+ *  - `{ toolName, error, kind: 'thrown' }`        — it threw a `tool-error`
+ *  - `{ toolName, error, kind: 'interrupted' }`   — no result and no throw (an
+ *      abort / server restart mid-step). `kind` is MANDATORY: without it a
+ *      synthetic "Tool call did not complete." is indistinguishable from a real
+ *      hard-fail and pollutes any error-rate scan. The distinction is STRUCTURAL
+ *      (an `errorsById` hit vs the synthetic fallback branch), NOT a per-tool
+ *      classifier — soft failures stay OUT of the trace (they live in
+ *      `metadata.parts` outputs; a per-tool mirror would persist its own bugs).
+ *
+ * Rows carry `metadata.toolTraceVersion: 2` (set by {@link flushAssistant}) so a
+ * dual-shape query can branch on the era. Old rows are NOT migrated (rewriting
+ * giant jsonb is the very WAL churn this removes); see docs/reading-ai-logs.md.
  */
 export function serializeSteps(
   steps: ReadonlyArray<{
-    toolCalls?: ReadonlyArray<{ toolName?: string; input?: unknown }>;
-    toolResults?: ReadonlyArray<{ toolName?: string; output?: unknown }>;
+    toolCalls?: ReadonlyArray<{
+      toolCallId?: string;
+      toolName?: string;
+      input?: unknown;
+    }>;
+    toolResults?: ReadonlyArray<{ toolCallId?: string; toolName?: string }>;
     content?: ReadonlyArray<{
       type?: string;
+      toolCallId?: string;
       toolName?: string;
       error?: unknown;
     }>;
   }>,
 ): unknown {
-  const calls: Array<{
-    toolName?: string;
-    input?: unknown;
-    output?: unknown;
-    error?: string;
-  }> = [];
+  const calls: Array<
+    | { toolName?: string; input?: unknown }
+    | { toolName?: string; ok: true }
+    | { toolName?: string; error: string; kind: 'thrown' | 'interrupted' }
+  > = [];
   for (const step of steps ?? []) {
+    // Index this step's results + thrown errors by tool call id, so each call is
+    // paired with its outcome (mirrors assistantParts' pairing exactly).
+    const resultIds = new Set<string>();
+    for (const r of step.toolResults ?? []) {
+      if (r.toolCallId) resultIds.add(r.toolCallId);
+    }
+    const errorsById = new Map<string, unknown>();
+    for (const part of step.content ?? []) {
+      if (part.type === 'tool-error' && part.toolCallId) {
+        errorsById.set(part.toolCallId, part.error);
+      }
+    }
     for (const call of step.toolCalls ?? []) {
       calls.push({ toolName: call.toolName, input: call.input });
-    }
-    for (const r of step.toolResults ?? []) {
-      calls.push({ toolName: r.toolName, output: compactToolOutput(r.output) });
-    }
-    // ai@6 surfaces a THROWN tool failure as a `tool-error` content part, NOT as
-    // a `toolResults` entry. Record it as its own paired element (mirroring how a
-    // successful result is appended) so the failure and its reason survive in the
-    // trace instead of leaving an orphaned call with no result.
-    for (const part of step.content ?? []) {
-      if (part.type === 'tool-error') {
+      if (call.toolCallId && resultIds.has(call.toolCallId)) {
+        // Success: the output itself lives in metadata.parts, not here.
+        calls.push({ toolName: call.toolName, ok: true });
+      } else if (call.toolCallId && errorsById.has(call.toolCallId)) {
+        // Hard fail: the tool threw. Persist the real (bounded) reason.
         calls.push({
-          toolName: part.toolName,
-          error: normalizeToolError(part.error),
+          toolName: call.toolName,
+          error: normalizeToolError(errorsById.get(call.toolCallId)),
+          kind: 'thrown',
+        });
+      } else {
+        // Neither a result nor a throw: interrupted mid-step (abort/restart).
+        // Marked structurally so it never inflates a thrown-error count.
+        calls.push({
+          toolName: call.toolName,
+          error: TOOL_CALL_INCOMPLETE_TEXT,
+          kind: 'interrupted',
         });
       }
     }

apps/server/src/core/ai-chat/ai-chat.step-marker.spec.ts

@@ -0,0 +1,65 @@
+import { flushAssistant } from './ai-chat.service';
+
+/**
+ * #491 STEP MARKER — `metadata.stepsPersisted` is written by the SAME flush that
+ * builds `metadata.parts`, so the marker can never disagree with the persisted
+ * parts (the step-alignment anchor the resume stack builds on). These are
+ * PROPERTY tests: they assert the marker tracks the number of FINISHED steps for
+ * every flush shape.
+ */
+
+// A finished step carrying one line of text and one tool call/result.
+function step(i: number) {
+  return {
+    text: `step ${i}`,
+    toolCalls: [
+      { toolCallId: `c${i}`, toolName: 'getPage', input: { id: `p${i}` } },
+    ],
+    toolResults: [
+      { toolCallId: `c${i}`, toolName: 'getPage', output: { title: `T${i}` } },
+    ],
+  };
+}
+
+describe('flushAssistant step marker (#491)', () => {
+  it('seed (no steps) → stepsPersisted 0', () => {
+    const f = flushAssistant([], '', 'streaming');
+    expect(f.metadata.stepsPersisted).toBe(0);
+  });
+
+  it('PROPERTY: stepsPersisted equals the number of FINISHED steps, for any N', () => {
+    for (let n = 0; n <= 6; n++) {
+      const steps = Array.from({ length: n }, (_, i) => step(i));
+      const f = flushAssistant(steps, '', 'streaming');
+      expect(f.metadata.stepsPersisted).toBe(n);
+      // ...and the parts actually contain those N steps' text (marker agrees with
+      // the persisted parts — the atomicity the whole design relies on).
+      const parts = f.metadata.parts as Array<Record<string, unknown>>;
+      const textParts = parts.filter((p) => p.type === 'text');
+      expect(textParts).toHaveLength(n);
+    }
+  });
+
+  it('an in-progress trailing partial does NOT increment the marker', () => {
+    // 2 finished steps + a partial (not-yet-finished) trailing text: the marker
+    // counts only the CONFIRMED step boundaries, not the partial.
+    const f = flushAssistant([step(0), step(1)], 'partial third step', 'error', {
+      error: 'boom',
+    });
+    expect(f.metadata.stepsPersisted).toBe(2);
+    // The partial text IS persisted in parts (so the user sees it), but it is not a
+    // counted step.
+    const parts = f.metadata.parts as Array<Record<string, unknown>>;
+    expect(parts[parts.length - 1]).toEqual({
+      type: 'text',
+      text: 'partial third step',
+    });
+  });
+
+  it('terminal completed flush counts all finished steps', () => {
+    const f = flushAssistant([step(0), step(1), step(2)], '', 'completed', {
+      finishReason: 'stop',
+    });
+    expect(f.metadata.stepsPersisted).toBe(3);
+  });
+});

apps/server/src/core/ai-chat/ai-chat.write-volume.int-spec.ts

@@ -0,0 +1,209 @@
+import { randomBytes } from 'crypto';
+import { Client } from 'pg';
+import { flushAssistant, serializeSteps } from './ai-chat.service';
+
+/**
+ * #490 write-volume regression — an OBSERVABLE-PROPERTY test on a LIVE Postgres,
+ * not "bytes through a mock repo" (a mock measures exactly the thing that does not
+ * hurt). It drives a realistic 50-step run where each step returns a ~100 KB tool
+ * output and, at every `onStepFinish`, UPDATEs the assistant row the way the
+ * service does — then reads the REAL write volume via the `pg_current_wal_lsn()`
+ * delta around the run.
+ *
+ * The property proven: v2 stores each tool OUTPUT only in `metadata.parts`, no
+ * longer ALSO in the `tool_calls` trace. So:
+ *   1. the trace (`tool_calls`) column's write volume is now O(Σ steps) — tiny,
+ *      linear outcome flags — vs the pre-#490 O(N²) that re-persisted every prior
+ *      output on every step; and
+ *   2. the FULL-row write volume drops sharply (the duplicated output copy is gone).
+ *
+ * Connects to the local gitmost test Postgres (docker `gitmost-test-pg` on :5432);
+ * SKIPS cleanly when that DB is not reachable so it never breaks a DB-less CI.
+ */
+const CONN =
+  process.env.WAL_TEST_DATABASE_URL ??
+  'postgresql://docmost:docmost_dev_pw@localhost:5432/docmost';
+
+// A step whose tool output is ~100 KB (a page read), in the SDK StepLike shape.
+// The body is INCOMPRESSIBLE random text — a `'x'.repeat()` filler would TOAST-
+// compress to nothing and hide the real write volume (a page body does not).
+function makeStep(i: number, outputBytes = 100_000) {
+  const body = randomBytes(Math.ceil(outputBytes * 0.75)).toString('base64');
+  return {
+    text: `step ${i} reasoning`,
+    toolCalls: [{ toolCallId: `c${i}`, toolName: 'getPage', input: { id: `p${i}` } }],
+    toolResults: [
+      {
+        toolCallId: `c${i}`,
+        toolName: 'getPage',
+        output: { id: `p${i}`, title: `Page ${i}`, body },
+      },
+    ],
+  };
+}
+
+// The pre-#490 (v1) trace: outputs stored a SECOND time in `tool_calls`
+// (the duplication #490 removed). Mirrors the OLD serializeSteps shape.
+function v1Trace(steps: ReturnType<typeof makeStep>[]): unknown {
+  const calls: unknown[] = [];
+  for (const s of steps) {
+    for (const c of s.toolCalls) calls.push({ toolName: c.toolName, input: c.input });
+    for (const r of s.toolResults)
+      calls.push({ toolName: r.toolName, output: r.output });
+  }
+  return calls;
+}
+
+async function walDelta(
+  client: Client,
+  fn: () => Promise<void>,
+): Promise<number> {
+  const before = (await client.query('SELECT pg_current_wal_lsn() AS l')).rows[0]
+    .l as string;
+  await fn();
+  // NOTE: do NOT pg_switch_wal() here — a segment switch pads the LSN to the next
+  // 16 MB boundary and would swamp the actual write delta. The raw LSN advances by
+  // the bytes of WAL emitted, which is exactly what we want to measure.
+  const after = (await client.query('SELECT pg_current_wal_lsn() AS l')).rows[0]
+    .l as string;
+  return Number(
+    (await client.query('SELECT pg_wal_lsn_diff($1,$2) AS d', [after, before]))
+      .rows[0].d,
+  );
+}
+
+describe('#490 write-volume on a live Postgres (pg_current_wal_lsn delta)', () => {
+  let client: Client | undefined;
+  let available = false;
+
+  beforeAll(async () => {
+    try {
+      client = new Client(CONN);
+      await client.connect();
+      await client.query('SELECT pg_current_wal_lsn()');
+      available = true;
+    } catch {
+      available = false;
+      client = undefined;
+    }
+  });
+
+  afterAll(async () => {
+    await client?.end().catch(() => undefined);
+  });
+
+  const STEPS = 50;
+
+  it('v2 trace write volume is O(Σ steps) — a tiny fraction of the v1 duplicate', async () => {
+    if (!available || !client) {
+      console.warn('SKIP: gitmost-test-pg not reachable; skipping WAL test.');
+      return;
+    }
+    const c = client;
+    // Isolated table so we measure only the tool_calls (trace) column's writes.
+    await c.query('DROP TABLE IF EXISTS _wal_trace');
+    await c.query('CREATE TABLE _wal_trace(id int primary key, tool_calls jsonb)');
+    await c.query("INSERT INTO _wal_trace VALUES (1, '[]'::jsonb)");
+
+    const steps: ReturnType<typeof makeStep>[] = [];
+
+    // v1: each step re-persists ALL prior outputs into the trace (the O(N²) churn).
+    const v1 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        await c.query('UPDATE _wal_trace SET tool_calls=$1 WHERE id=1', [
+          JSON.stringify(v1Trace(acc)),
+        ]);
+      }
+      steps.push(...acc);
+    });
+
+    await c.query("UPDATE _wal_trace SET tool_calls='[]'::jsonb WHERE id=1");
+
+    // v2: the REAL serializeSteps — outcome flags only, NO outputs.
+    const v2 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        await c.query('UPDATE _wal_trace SET tool_calls=$1 WHERE id=1', [
+          JSON.stringify(serializeSteps(acc)),
+        ]);
+      }
+    });
+
+    await c.query('DROP TABLE IF EXISTS _wal_trace');
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[#490 WAL] trace column over ${STEPS} steps: v1=${(v1 / 1e6).toFixed(1)}MB ` +
+        `v2=${(v2 / 1e6).toFixed(2)}MB (${(v1 / v2).toFixed(0)}x smaller)`,
+    );
+
+    // The trace no longer carries outputs: v2 is a tiny fraction of v1's WAL.
+    expect(v2).toBeLessThan(v1 * 0.1);
+    // And v2's trace WAL is small in absolute terms — O(Σ steps) of flags, not
+    // O(N² × output). 50 steps of ~40-byte flags is well under a few MB of WAL.
+    expect(v2).toBeLessThan(5_000_000);
+    // v1's duplicate alone is huge (≈ the 100 KB output re-written N² times).
+    expect(v1).toBeGreaterThan(50_000_000);
+  }, 120_000);
+
+  it('the full assistant row write drops sharply once the duplicate is gone', async () => {
+    if (!available || !client) return;
+    const c = client;
+    await c.query('DROP TABLE IF EXISTS _wal_full');
+    await c.query(
+      'CREATE TABLE _wal_full(id int primary key, content text, tool_calls jsonb, metadata jsonb, status text)',
+    );
+    await c.query("INSERT INTO _wal_full VALUES (1, '', '[]'::jsonb, '{}'::jsonb, 'streaming')");
+
+    const writeRow = async (patch: {
+      content: string;
+      toolCalls: unknown;
+      metadata: unknown;
+      status: string;
+    }) =>
+      c.query(
+        'UPDATE _wal_full SET content=$1, tool_calls=$2, metadata=$3, status=$4 WHERE id=1',
+        [
+          patch.content,
+          JSON.stringify(patch.toolCalls ?? null),
+          JSON.stringify(patch.metadata),
+          patch.status,
+        ],
+      );
+
+    // v2 (real flushAssistant): outputs live once, in metadata.parts.
+    const v2 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        await writeRow(flushAssistant(acc as never, '', 'streaming'));
+      }
+    });
+
+    await c.query("UPDATE _wal_full SET content='', tool_calls='[]'::jsonb, metadata='{}'::jsonb WHERE id=1");
+
+    // v1: same row PLUS the duplicated outputs in the trace column.
+    const v1 = await walDelta(c, async () => {
+      const acc: ReturnType<typeof makeStep>[] = [];
+      for (let i = 0; i < STEPS; i++) {
+        acc.push(makeStep(i));
+        const f = flushAssistant(acc as never, '', 'streaming');
+        await writeRow({ ...f, toolCalls: v1Trace(acc) });
+      }
+    });
+
+    await c.query('DROP TABLE IF EXISTS _wal_full');
+
+    // eslint-disable-next-line no-console
+    console.log(
+      `[#490 WAL] full row over ${STEPS} steps: v1=${(v1 / 1e6).toFixed(1)}MB ` +
+        `v2=${(v2 / 1e6).toFixed(1)}MB (saved ${((1 - v2 / v1) * 100).toFixed(0)}%)`,
+    );
+
+    // Removing the duplicated trace copy is a large, real write-volume reduction.
+    expect(v2).toBeLessThan(v1 * 0.75);
+  }, 120_000);
+});

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

@@ -1,4 +1,10 @@
-import { IsOptional, IsString, MaxLength, MinLength } from 'class-validator';
+import {
+  IsISO8601,
+  IsOptional,
+  IsString,
+  MaxLength,
+  MinLength,
+} from 'class-validator';
 
 /** Identify a chat by id (workspace-scoped on the server). */
 export class ChatIdDto {
@@ -37,6 +43,24 @@ export class GetChatMessagesDto {
   cursor?: string;
 }
 
+/**
+ * Delta poll (#491): pull the chat's rows changed since `cursor` (a DB-clock
+ * timestamp from the previous poll) plus the current run fact — the degraded-poll
+ * fallback's payload, replacing the full infinite-query refetch. Omit `cursor` on
+ * the first poll (returns just a fresh cursor to start the chain).
+ */
+export class GetChatDeltaDto {
+  @IsString()
+  chatId: string;
+
+  // ISO-8601 timestamp echoed from the previous poll's response. Validated as
+  // ISO-8601 (not a bare string): a malformed cursor would otherwise reach the
+  // `::timestamptz` cast in findByChatUpdatedAfter and 500 instead of a clean 400.
+  @IsOptional()
+  @IsISO8601()
+  cursor?: string;
+}
+
 /** Resolve the chat bound to a document (the page's most-recent owned chat). */
 export class BoundChatDto {
   @IsString()

apps/server/src/core/ai-chat/history-budget.spec.ts

@@ -0,0 +1,266 @@
+import type { ModelMessage } from 'ai';
+import {
+  resolveReplayBudget,
+  isContextOverflowError,
+  estimateMessagesTokens,
+  trimHistoryForReplay,
+  REPLAY_BUDGET_DEFAULT_TOKENS,
+  REPLAY_TRUNCATION_MARKER,
+  REPLAY_TURN_COLLAPSED_MARKER,
+} from './history-budget';
+
+describe('resolveReplayBudget', () => {
+  it('uses floor(0.7 x window) for a configured window (no cap)', () => {
+    // 0.7 x 60k = 42k
+    expect(resolveReplayBudget(60_000)).toEqual({
+      thresholdTokens: 42_000,
+      usedDefault: false,
+    });
+    // 0.7 x 1M = 700k — NOT capped (anti-brick vs the window, not a cost limiter).
+    expect(resolveReplayBudget(1_000_000)).toEqual({
+      thresholdTokens: 700_000,
+      usedDefault: false,
+    });
+  });
+
+  it('accepts the raw ::text stored form', () => {
+    expect(resolveReplayBudget('60000').thresholdTokens).toBe(42_000);
+  });
+
+  // The crux (#490): a chat with NO context window configured must STILL be
+  // budgeted — those are exactly the installs that hit terminal overflow.
+  it('applies the flat default when the window is unset/empty', () => {
+    expect(resolveReplayBudget(undefined)).toEqual({
+      thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS,
+      usedDefault: true,
+    });
+    expect(resolveReplayBudget('')).toEqual({
+      thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS,
+      usedDefault: true,
+    });
+    expect(resolveReplayBudget('   ')).toEqual({
+      thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS,
+      usedDefault: true,
+    });
+  });
+
+  it('treats an explicit 0 as the off-switch (distinct from unset)', () => {
+    expect(resolveReplayBudget(0)).toEqual({
+      thresholdTokens: null,
+      usedDefault: false,
+    });
+    expect(resolveReplayBudget('0')).toEqual({
+      thresholdTokens: null,
+      usedDefault: false,
+    });
+  });
+
+  it('falls back to the default on a negative/garbage value', () => {
+    expect(resolveReplayBudget(-5).usedDefault).toBe(true);
+    expect(resolveReplayBudget('abc').usedDefault).toBe(true);
+  });
+});
+
+describe('isContextOverflowError', () => {
+  it('classifies a real provider 400 context-overflow shape', () => {
+    // OpenAI-compatible shape.
+    expect(
+      isContextOverflowError({
+        statusCode: 400,
+        message:
+          "This model's maximum context length is 128000 tokens. However, your messages resulted in 214000 tokens. Please reduce the length of the messages.",
+      }),
+    ).toBe(true);
+    // Anthropic-style wording.
+    expect(
+      isContextOverflowError({
+        status: 400,
+        message: 'prompt is too long: 250000 tokens > 200000 maximum',
+      }),
+    ).toBe(true);
+    // Nested body + string status.
+    expect(
+      isContextOverflowError({
+        response: { status: '400' },
+        message: 'input is too long for the requested model',
+      }),
+    ).toBe(true);
+    // Error instance with the cause carrying the body.
+    const e = new Error('Bad request');
+    (e as any).statusCode = 400;
+    (e as any).cause = new Error('maximum context window exceeded');
+    expect(isContextOverflowError(e)).toBe(true);
+  });
+
+  it('does NOT classify unrelated 400s or auth/rate-limit errors', () => {
+    expect(
+      isContextOverflowError({ statusCode: 400, message: 'invalid tool schema' }),
+    ).toBe(false);
+    expect(
+      isContextOverflowError({
+        statusCode: 429,
+        message: 'context length exceeded but rate limited',
+      }),
+    ).toBe(false);
+    expect(isContextOverflowError({ statusCode: 500, message: 'server error' })).toBe(
+      false,
+    );
+    expect(isContextOverflowError(undefined)).toBe(false);
+    expect(isContextOverflowError('some random string')).toBe(false);
+  });
+});
+
+// Helpers to build ModelMessage fixtures in the ai@6 shape.
+const userMsg = (text: string): ModelMessage =>
+  ({ role: 'user', content: [{ type: 'text', text }] }) as ModelMessage;
+const assistantMsg = (
+  text: string,
+  toolCallId?: string,
+  toolName?: string,
+): ModelMessage =>
+  ({
+    role: 'assistant',
+    content: [
+      { type: 'text', text },
+      ...(toolCallId
+        ? [{ type: 'tool-call', toolCallId, toolName, input: {} }]
+        : []),
+    ],
+  }) as ModelMessage;
+const toolMsg = (
+  toolCallId: string,
+  toolName: string,
+  value: unknown,
+): ModelMessage =>
+  ({
+    role: 'tool',
+    content: [
+      { type: 'tool-result', toolCallId, toolName, output: { type: 'json', value } },
+    ],
+  }) as ModelMessage;
+
+describe('trimHistoryForReplay', () => {
+  it('null budget disables trimming (returns the same reference)', () => {
+    const msgs = [userMsg('hi'), assistantMsg('yo')];
+    const r = trimHistoryForReplay(msgs, null);
+    expect(r.trimmed).toBe(false);
+    expect(r.messages).toBe(msgs);
+  });
+
+  it('leaves history under budget untouched (same reference)', () => {
+    const msgs = [userMsg('hi'), assistantMsg('a short answer')];
+    const r = trimHistoryForReplay(msgs, 100_000);
+    expect(r.trimmed).toBe(false);
+    expect(r.messages).toBe(msgs);
+  });
+
+  it('truncates OLD tool outputs but keeps recent turns full', () => {
+    const big = 'X'.repeat(40_000); // ~16k tokens on its own
+    const msgs: ModelMessage[] = [];
+    // 6 OLD turns (indices 0..5), each with a huge tool output.
+    for (let i = 0; i < 6; i++) {
+      msgs.push(userMsg(`old q${i}`));
+      msgs.push(assistantMsg('looking', `c${i}`, 'getPage'));
+      msgs.push(toolMsg(`c${i}`, 'getPage', { body: big }));
+      msgs.push(assistantMsg(`old a${i}`));
+    }
+    // 3 small recent turns, then the CURRENT turn with its own huge tool output.
+    // With REPLAY_KEEP_RECENT_TURNS=4 the last 4 user-turns stay full, so only
+    // these small recent turns + the current big one are kept full; the 6 old
+    // turns above fall in the trim region.
+    for (let i = 0; i < 3; i++) {
+      msgs.push(userMsg(`recent q${i}`));
+      msgs.push(assistantMsg(`recent a${i}`));
+    }
+    msgs.push(userMsg('current q'));
+    msgs.push(assistantMsg('looking', 'cR', 'getPage'));
+    msgs.push(toolMsg('cR', 'getPage', { body: big }));
+    msgs.push(assistantMsg('current a'));
+
+    // Budget large enough that phase-1 tool truncation alone brings it under.
+    const r = trimHistoryForReplay(msgs, 30_000);
+    expect(r.trimmed).toBe(true);
+    const flat = JSON.stringify(r.messages);
+    // The CURRENT turn's tool output survives in full.
+    expect(flat).toContain(big);
+    // Old outputs were truncated with the marker.
+    expect(flat).toContain(REPLAY_TRUNCATION_MARKER);
+    // Phase 1 sufficed: the oldest turns were NOT collapsed.
+    expect(flat).not.toContain(REPLAY_TURN_COLLAPSED_MARKER);
+    expect(estimateMessagesTokens(r.messages)).toBeLessThan(
+      estimateMessagesTokens(msgs),
+    );
+  });
+
+  it('collapses the oldest turns when tool truncation is not enough', () => {
+    // Many turns with LARGE assistant TEXT (not tool output) so phase 1 can't help.
+    const bigText = 'слово '.repeat(8_000); // large Cyrillic text per turn
+    const msgs: ModelMessage[] = [];
+    for (let i = 0; i < 12; i++) {
+      msgs.push(userMsg(`q${i}`));
+      msgs.push(assistantMsg(bigText));
+    }
+    const r = trimHistoryForReplay(msgs, 30_000);
+    expect(r.trimmed).toBe(true);
+    // Oldest turns collapsed; result fits (best-effort) and is much smaller.
+    expect(estimateMessagesTokens(r.messages)).toBeLessThan(
+      estimateMessagesTokens(msgs),
+    );
+    // The LAST turn's text is preserved in full (recent turns stay full).
+    expect(JSON.stringify(r.messages[r.messages.length - 1])).toContain(bigText);
+  });
+
+  it('is deterministic / byte-stable for identical inputs', () => {
+    const big = 'Y'.repeat(30_000);
+    const build = (): ModelMessage[] => {
+      const m: ModelMessage[] = [];
+      for (let i = 0; i < 10; i++) {
+        m.push(userMsg(`q${i}`));
+        m.push(assistantMsg('t', `c${i}`, 'getPage'));
+        m.push(toolMsg(`c${i}`, 'getPage', { body: big }));
+      }
+      return m;
+    };
+    const a = trimHistoryForReplay(build(), 15_000);
+    const b = trimHistoryForReplay(build(), 15_000);
+    expect(JSON.stringify(a.messages)).toBe(JSON.stringify(b.messages));
+  });
+
+  it('never leaves an unpaired tool-call after collapsing (balanced history)', () => {
+    const big = 'Z'.repeat(40_000);
+    const msgs: ModelMessage[] = [];
+    for (let i = 0; i < 10; i++) {
+      msgs.push(userMsg(`q${i}`));
+      msgs.push(assistantMsg('t', `c${i}`, 'getPage'));
+      msgs.push(toolMsg(`c${i}`, 'getPage', { body: big }));
+    }
+    const r = trimHistoryForReplay(msgs, 8_000);
+    // Count tool-call vs tool-result parts in the trimmed output.
+    let calls = 0;
+    let results = 0;
+    for (const m of r.messages) {
+      if (!Array.isArray(m.content)) continue;
+      for (const p of m.content as Array<{ type?: string }>) {
+        if (p.type === 'tool-call') calls++;
+        if (p.type === 'tool-result' || p.type === 'tool-error') results++;
+      }
+    }
+    // Every surviving tool-call has a surviving result (collapsing drops BOTH).
+    expect(calls).toBe(results);
+    // Collapsed turns carry the marker.
+    expect(JSON.stringify(r.messages)).toContain(REPLAY_TURN_COLLAPSED_MARKER);
+  });
+
+  it('respects the provider fact: under-budget contextTokens skips trimming', () => {
+    const big = 'W'.repeat(60_000);
+    const msgs = [
+      userMsg('q'),
+      assistantMsg('t', 'c1', 'getPage'),
+      toolMsg('c1', 'getPage', { body: big }),
+    ];
+    // char-estimate is high, but the provider says we are well under budget.
+    const r = trimHistoryForReplay(msgs, 100_000, 5_000);
+    expect(r.trimmed).toBe(false);
+    expect(r.messages).toBe(msgs);
+  });
+});

apps/server/src/core/ai-chat/history-budget.ts

@@ -0,0 +1,375 @@
+/**
+ * History-replay token budget (#490).
+ *
+ * The whole persisted conversation is replayed to the provider on EVERY turn, so
+ * a long chat eventually exceeds the model's context window and the provider 400s
+ * on every turn — terminally (the chat "bricks"). This module bounds the replayed
+ * history at REPLAY TIME only: it never mutates what is persisted (the DB stays
+ * the full record), and its output is a deterministic, byte-stable function of its
+ * input so the trimmed prefix is identical turn to turn (provider prompt-cache
+ * friendliness — real money on long chats).
+ *
+ * The PRIMARY signal is the provider's own fact: `metadata.contextTokens` from the
+ * last turn. The chars-based {@link estimateTokens} (shared with the client) is
+ * used only for the DELTA of not-yet-sent messages, to decide WHAT to trim, and as
+ * the fallback for chats with no usage yet.
+ */
+import type { ModelMessage } from 'ai';
+import { estimateTokens } from '@docmost/token-estimate';
+
+/** Flat default budget when no context window is configured (tokens). */
+export const REPLAY_BUDGET_DEFAULT_TOKENS = 100_000;
+/** Fraction of a configured context window used as the budget. */
+export const REPLAY_BUDGET_WINDOW_FRACTION = 0.7;
+/**
+ * Fraction of the normal budget used for the REACTIVE re-trim after a provider
+ * context-overflow 400 — the preventive estimate under-counted, so cut harder.
+ */
+export const REPLAY_AGGRESSIVE_FRACTION = 0.5;
+/**
+ * Turns (a user message + its assistant/tool replies) kept FULL at the tail,
+ * including the current one — never trimmed. Older turns are compacted first.
+ */
+export const REPLAY_KEEP_RECENT_TURNS = 4;
+/** Leading chars kept from a truncated old tool output. */
+export const REPLAY_TOOL_OUTPUT_HEAD = 800;
+/** Trailing chars kept from a truncated old tool output. */
+export const REPLAY_TOOL_OUTPUT_TAIL = 300;
+/** Marker inserted where an old tool output was truncated for replay. */
+export const REPLAY_TRUNCATION_MARKER =
+  '[…truncated for replay; call the tool again to read the full output]';
+/** Marker for a whole old turn collapsed to its text. */
+export const REPLAY_TURN_COLLAPSED_MARKER =
+  '[earlier tool activity omitted for replay]';
+
+export interface ReplayBudget {
+  /** Token threshold above which replay history is trimmed; `null` = OFF. */
+  thresholdTokens: number | null;
+  /** True when the flat default was used (no context window configured). */
+  usedDefault: boolean;
+}
+
+/**
+ * Resolve the replay budget from the RAW stored `chatContextWindow` (text/number).
+ *  - a positive value  -> `floor(fraction × window)` (NO cap — the budgeter is
+ *    anti-brick protection against the window itself, not a cost/economy limiter,
+ *    exactly as the codebase already treats maxOutputTokens; the reactive branch
+ *    still guarantees anti-brick regardless of how high this budget is)
+ *  - explicit `0`       -> OFF (admin opt-out; `null` threshold)
+ *  - unset/empty/invalid-> the flat default (still protects — the installations
+ *    that hit terminal overflow are exactly the ones that never set a window)
+ *
+ * Note the raw value is needed because the parsed `chatContextWindow` collapses
+ * both `0` and unset to `undefined`, which would erase the explicit off-switch.
+ */
+export function resolveReplayBudget(rawContextWindow: unknown): ReplayBudget {
+  let n: number | undefined;
+  if (typeof rawContextWindow === 'number') {
+    n = rawContextWindow;
+  } else if (typeof rawContextWindow === 'string') {
+    const t = rawContextWindow.trim();
+    n = t === '' ? undefined : Number(t);
+  }
+  // Unset / empty / non-numeric / negative -> flat default (the protective case).
+  if (n === undefined || !Number.isFinite(n) || n < 0) {
+    return { thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS, usedDefault: true };
+  }
+  // Explicit 0 -> off-switch.
+  if (n === 0) {
+    return { thresholdTokens: null, usedDefault: false };
+  }
+  return {
+    thresholdTokens: Math.floor(REPLAY_BUDGET_WINDOW_FRACTION * n),
+    usedDefault: false,
+  };
+}
+
+/**
+ * The effective replay threshold for THIS turn, given the base budget and whether
+ * the PREVIOUS turn hit a context-overflow 400 (the reactive-recovery signal,
+ * `metadata.replayOverflow`). On recovery the base budget is scaled down by
+ * {@link REPLAY_AGGRESSIVE_FRACTION}: the overflowing turn produced no usage
+ * signal, so the preventive estimate under-counted and a normal-threshold trim may
+ * not shrink enough to fit — this harder cut is what un-bricks the chat.
+ *
+ * A `null` base budget (trimming OFF) is passed through unchanged: an explicit
+ * off-switch is never overridden by the recovery path.
+ */
+export function resolveEffectiveReplayThreshold(
+  thresholdTokens: number | null,
+  priorOverflowed: boolean,
+): number | null {
+  if (!priorOverflowed || thresholdTokens == null) return thresholdTokens;
+  return Math.floor(thresholdTokens * REPLAY_AGGRESSIVE_FRACTION);
+}
+
+/**
+ * True when a provider error is a CONTEXT-OVERFLOW rejection (the prompt exceeds
+ * the model's window). Providers surface this as an HTTP 400 with a recognizable
+ * message; match both the status and the message patterns robustly across
+ * OpenAI-compatible / Anthropic / Gemini wordings, since the exact shape varies.
+ */
+export function isContextOverflowError(error: unknown): boolean {
+  const status = extractStatus(error);
+  const msg = extractMessage(error).toLowerCase();
+  // Message patterns seen across providers for "prompt too long".
+  const overflowPattern =
+    /context (?:length|window)|maximum context|too many tokens|too large for|reduce the length|prompt is too long|input (?:is )?too long|exceeds? the (?:maximum )?(?:context|token)|maximum.*tokens|string too long/;
+  if (!overflowPattern.test(msg)) return false;
+  // A 400/413 with an overflow-shaped message is an overflow. Some providers
+  // omit/rewrite the status, so accept the message match when the status is
+  // unknown, but reject it for auth/rate-limit statuses that never mean overflow.
+  if (status === 400 || status === 413) return true;
+  if (status === 401 || status === 403 || status === 429) return false;
+  return true;
+}
+
+function extractStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const e = error as Record<string, unknown>;
+  for (const k of ['statusCode', 'status']) {
+    const v = e[k];
+    if (typeof v === 'number') return v;
+    if (typeof v === 'string' && /^\d+$/.test(v)) return Number(v);
+  }
+  // Nested (e.g. { response: { status } } / { cause: { statusCode } }).
+  for (const k of ['response', 'cause', 'data']) {
+    const nested = e[k];
+    if (nested && typeof nested === 'object') {
+      const s = extractStatus(nested);
+      if (s !== undefined) return s;
+    }
+  }
+  return undefined;
+}
+
+function extractMessage(error: unknown): string {
+  if (error == null) return '';
+  if (typeof error === 'string') return error;
+  if (error instanceof Error) {
+    // Include nested causes (provider libs wrap the real body in `cause`).
+    const cause = (error as { cause?: unknown }).cause;
+    return `${error.message} ${cause ? extractMessage(cause) : ''}`;
+  }
+  if (typeof error === 'object') {
+    const e = error as Record<string, unknown>;
+    const parts: string[] = [];
+    for (const k of ['message', 'error', 'body', 'responseBody', 'data']) {
+      const v = e[k];
+      if (typeof v === 'string') parts.push(v);
+      else if (v && typeof v === 'object') parts.push(extractMessage(v));
+    }
+    return parts.join(' ');
+  }
+  return String(error);
+}
+
+/** Rough token size of a ModelMessage array via the shared chars estimator. */
+export function estimateMessagesTokens(
+  messages: ReadonlyArray<ModelMessage>,
+): number {
+  let total = 0;
+  for (const m of messages) {
+    total += estimateTokens(serializeContent(m.content));
+  }
+  return total;
+}
+
+function serializeContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  try {
+    return JSON.stringify(content) ?? '';
+  } catch {
+    return '';
+  }
+}
+
+/** Deep JSON string of an arbitrary value, bounded so estimation never throws. */
+function stringifyValue(value: unknown): string {
+  if (typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export interface TrimResult {
+  messages: ModelMessage[];
+  /** Whether any trimming was applied. */
+  trimmed: boolean;
+  /** Estimated tokens of the returned messages (chars-based). */
+  estimatedTokens: number;
+}
+
+/**
+ * Bound the replayed history to `budgetTokens`, deterministically. Returns the
+ * SAME array reference (no copy) when nothing needs trimming, so the common case
+ * is free and byte-identical. Trimming order (spec #490):
+ *   1. truncate OLD turns' tool outputs (head+tail + marker) — the bulk of the size
+ *   2. mechanically collapse the OLDEST turns to their text (concatenation, no LLM)
+ *   3. the current + last {@link REPLAY_KEEP_RECENT_TURNS} turns stay FULL
+ *
+ * `budgetTokens === null` disables trimming. `priorContextTokens` (the provider's
+ * fact from last turn) short-circuits the decision: when it is known and already
+ * under budget we skip trimming even if the char-estimate is higher (the provider
+ * count is authoritative). The char-estimate drives WHAT to cut.
+ */
+export function trimHistoryForReplay(
+  messages: ModelMessage[],
+  budgetTokens: number | null,
+  priorContextTokens?: number,
+): TrimResult {
+  if (budgetTokens == null) {
+    return { messages, trimmed: false, estimatedTokens: 0 };
+  }
+  const estimated = estimateMessagesTokens(messages);
+  // Decision signal: prefer the provider's fact (last turn's contextTokens) plus
+  // the estimated delta of the messages appended since; fall back to the pure
+  // char-estimate for a chat with no usage yet.
+  const projected =
+    priorContextTokens != null
+      ? Math.max(priorContextTokens, estimated)
+      : estimated;
+  if (projected <= budgetTokens) {
+    return { messages, trimmed: false, estimatedTokens: estimated };
+  }
+
+  // The tail we always keep full: from the Nth-from-last user message onward.
+  const boundary = recentBoundaryIndex(messages, REPLAY_KEEP_RECENT_TURNS);
+  const tail = messages.slice(boundary);
+  let head = messages.slice(0, boundary).map(cloneMessage);
+
+  // Phase 1: truncate old tool outputs.
+  for (const m of head) {
+    if (m.role === 'tool') truncateToolMessage(m);
+  }
+  let out = [...head, ...tail];
+  let est = estimateMessagesTokens(out);
+  if (est <= budgetTokens) {
+    return { messages: out, trimmed: true, estimatedTokens: est };
+  }
+
+  // Phase 2: collapse the oldest turns (in `head`) to their text, one at a time,
+  // from the oldest, until we fit or the whole head is collapsed.
+  const turns = splitTurns(head);
+  const collapsed: ModelMessage[] = [];
+  let i = 0;
+  for (; i < turns.length; i++) {
+    if (est <= budgetTokens) break;
+    collapsed.push(...collapseTurn(turns[i]));
+    // Re-estimate the whole prospective output.
+    const remaining = turns.slice(i + 1).flat();
+    out = [...collapsed, ...remaining, ...tail];
+    est = estimateMessagesTokens(out);
+  }
+  // Include any turns we didn't need to collapse.
+  const remaining = turns.slice(i).flat();
+  out = [...collapsed, ...remaining, ...tail];
+  est = estimateMessagesTokens(out);
+  return { messages: out, trimmed: true, estimatedTokens: est };
+}
+
+/** Index of the first message of the Nth-from-last user turn (0 if fewer). */
+function recentBoundaryIndex(
+  messages: ReadonlyArray<ModelMessage>,
+  keepTurns: number,
+): number {
+  const userIdx: number[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].role === 'user') userIdx.push(i);
+  }
+  if (userIdx.length <= keepTurns) return 0;
+  return userIdx[userIdx.length - keepTurns];
+}
+
+/** Split a message list into turns; each turn starts at a `user` message. */
+function splitTurns(messages: ModelMessage[]): ModelMessage[][] {
+  const turns: ModelMessage[][] = [];
+  for (const m of messages) {
+    if (m.role === 'user' || turns.length === 0) turns.push([m]);
+    else turns[turns.length - 1].push(m);
+  }
+  return turns;
+}
+
+/**
+ * Collapse a whole turn to its plain text (mechanical concatenation, not an LLM
+ * summary). Keeps the user message; replaces the assistant/tool messages with a
+ * single assistant text message = the assistant's concatenated text + a marker
+ * when tool activity was dropped. Dropping BOTH the tool-call and tool-result
+ * parts together keeps the rebuilt history balanced (no unpaired calls).
+ */
+function collapseTurn(turn: ModelMessage[]): ModelMessage[] {
+  const out: ModelMessage[] = [];
+  let assistantText = '';
+  let hadTools = false;
+  for (const m of turn) {
+    if (m.role === 'user') {
+      out.push(m);
+    } else if (m.role === 'assistant') {
+      const { text, tools } = extractAssistantText(m.content);
+      assistantText += text;
+      hadTools = hadTools || tools;
+    } else if (m.role === 'tool') {
+      hadTools = true;
+    } else {
+      out.push(m);
+    }
+  }
+  const note =
+    (assistantText ? assistantText.trimEnd() : '') +
+    (hadTools
+      ? `${assistantText ? '\n\n' : ''}${REPLAY_TURN_COLLAPSED_MARKER}`
+      : '');
+  if (note) out.push({ role: 'assistant', content: note } as ModelMessage);
+  return out;
+}
+
+function extractAssistantText(content: unknown): {
+  text: string;
+  tools: boolean;
+} {
+  if (typeof content === 'string') return { text: content, tools: false };
+  if (!Array.isArray(content)) return { text: '', tools: false };
+  let text = '';
+  let tools = false;
+  for (const part of content) {
+    const type = (part as { type?: string })?.type;
+    if (type === 'text') text += (part as { text?: string }).text ?? '';
+    else if (type === 'tool-call') tools = true;
+  }
+  return { text, tools };
+}
+
+/** Truncate every tool-result output in a `tool` message to head+tail+marker. */
+function truncateToolMessage(message: ModelMessage): void {
+  const content = message.content;
+  if (!Array.isArray(content)) return;
+  for (const part of content) {
+    const p = part as { type?: string; output?: { type?: string; value?: unknown } };
+    if (p.type !== 'tool-result' && p.type !== 'tool-error') continue;
+    if (!p.output) continue;
+    const raw = stringifyValue(p.output.value);
+    const budget = REPLAY_TOOL_OUTPUT_HEAD + REPLAY_TOOL_OUTPUT_TAIL;
+    if (raw.length <= budget + REPLAY_TRUNCATION_MARKER.length) continue;
+    const truncated =
+      raw.slice(0, REPLAY_TOOL_OUTPUT_HEAD) +
+      `\n${REPLAY_TRUNCATION_MARKER}\n` +
+      raw.slice(raw.length - REPLAY_TOOL_OUTPUT_TAIL);
+    // Represent the shrunk output as a text output (a valid tool-result output).
+    p.output = { type: 'text', value: truncated };
+  }
+}
+
+/** Shallow-ish clone so trimming never mutates the caller's (persisted-derived)
+ *  message objects — only the OLD region is cloned before it is edited. */
+function cloneMessage(m: ModelMessage): ModelMessage {
+  if (typeof m.content === 'string') return { ...m };
+  return {
+    ...m,
+    content: (m.content as unknown[]).map((p) =>
+      p && typeof p === 'object' ? { ...(p as object) } : p,
+    ),
+  } as ModelMessage;
+}

apps/server/src/database/migrations/20260707T120000-ai-chat-metadata.ts

@@ -0,0 +1,24 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // Chat-level metadata bag (#490). First use: the deferred-tool ACTIVATION set
+  // (`activatedTools`) is persisted here so it survives across turns — previously
+  // the set was reset every turn, forcing the model to re-run loadTools and pay a
+  // fresh round-trip to re-activate the same tools each turn. On load the stored
+  // set is intersected with the current valid deferred names, so an allowlist /
+  // role change can never inject a now-nonexistent tool.
+  //
+  // jsonb, defaulted to '{}' so every row (incl. pre-migration ones, backfilled
+  // by the default) is a readable object — the app never has to null-guard the
+  // bag itself, only individual keys.
+  await db.schema
+    .alterTable('ai_chats')
+    .addColumn('metadata', 'jsonb', (col) =>
+      col.notNull().defaultTo(sql`'{}'::jsonb`),
+    )
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.alterTable('ai_chats').dropColumn('metadata').execute();
+}

apps/server/src/database/repos/ai-chat/ai-chat-message.repo.delta.int-spec.ts

@@ -0,0 +1,280 @@
+import { randomUUID } from 'crypto';
+import { CamelCasePlugin, Kysely, sql } from 'kysely';
+import { PostgresJSDialect } from 'kysely-postgres-js';
+// NOT a default import: the project tsconfig is `module: commonjs` with NO
+// esModuleInterop, so `import postgres from 'postgres'` compiles to
+// `postgres_1.default(...)` and the CJS `postgres` export has no `.default` —
+// it threw in beforeAll, was swallowed as "DB unreachable", and SILENTLY voided
+// all six tests. Mirror the working integration harness (test/integration/db.ts).
+import * as postgres from 'postgres';
+import { AiChatMessageRepo } from './ai-chat-message.repo';
+import { AiChatRunRepo } from './ai-chat-run.repo';
+
+/**
+ * #491 delta-poll — OBSERVABLE-PROPERTY tests against a LIVE Postgres (the local
+ * gitmost test DB, docker `gitmost-test-pg` on :5432), not "rows through a mock"
+ * (a mock cannot observe the DB clock nor the overlap-window race — the very
+ * things that matter here). Drives the REAL repo methods (`findByChatUpdatedAfter`,
+ * the now()-stamped `update`) and asserts:
+ *   1. delta-relevant writes stamp `updatedAt` from the DB clock, not the app clock
+ *      (proven by faking the process clock far into the future and observing the
+ *      stamp stays on real DB time);
+ *   2. the poll returns only rows changed after the cursor, ordered, with a fresh
+ *      DB-clock cursor;
+ *   3. the "committed late but stamped earlier than the cursor" RACE is caught by
+ *      the overlap window (a naive `updatedAt > cursor` would MISS it);
+ *   4. the overlap GUARANTEES repeats across close polls — the contract behind the
+ *      client's idempotent merge (mergeById).
+ *
+ * INTEGRATION lane (`*.int-spec.ts`): runs under `test:int`, whose global-setup
+ * DROPS + RE-CREATES + MIGRATES `docmost_test`, so the real `ai_chat_messages` /
+ * `ai_chat_runs` tables EXIST here. (It was previously a `.spec.ts` defaulting to
+ * the UNmigrated dev `docmost`; in the CI unit lane — where `WAL_TEST_DATABASE_URL`
+ * is unset and only `test:int` migrates — that meant 5/6 ERROR
+ * `relation "ai_chat_messages" does not exist`, silently voiding coverage of the
+ * risky cursor/overlap logic. Renaming to `.int-spec.ts` + defaulting the DSN to
+ * `docmost_test` fixes the CI fidelity.)
+ *
+ * FK triggers are bypassed (`session_replication_role = replica`) so synthetic
+ * chat/workspace ids need no parent fixtures; a single pooled connection (max 1)
+ * keeps that session setting for every query. SKIPS cleanly when the DB is
+ * unreachable so a DB-less CI never breaks.
+ */
+const CONN =
+  process.env.WAL_TEST_DATABASE_URL ??
+  process.env.TEST_DATABASE_URL ??
+  'postgresql://docmost:docmost_dev_pw@localhost:5432/docmost_test';
+
+let db: Kysely<any>;
+let sqlClient: ReturnType<typeof postgres>;
+let msgRepo: AiChatMessageRepo;
+let runRepo: AiChatRunRepo;
+let reachable = false;
+
+const workspaceId = randomUUID();
+const chatId = randomUUID();
+
+beforeAll(async () => {
+  try {
+    sqlClient = postgres(CONN, { max: 1, onnotice: () => {} });
+    db = new Kysely<any>({
+      dialect: new PostgresJSDialect({ postgres: sqlClient }),
+      plugins: [new CamelCasePlugin()],
+    });
+    // Single connection keeps this session-scoped bypass for the whole suite.
+    await sql`set session_replication_role = replica`.execute(db);
+    await sql`select 1`.execute(db);
+    reachable = true;
+  } catch (err) {
+    reachable = false;
+    // A genuine connection failure (ECONNREFUSED etc.) is a legitimate skip on a
+    // DB-less CI. A PROGRAMMING error (bad import, typo, driver misuse) must NOT
+    // masquerade as "DB unreachable" and silently void the whole suite (that is
+    // exactly the bug that hid this spec's zero coverage) — rethrow it so the
+    // suite fails LOUDLY.
+    const msg = String((err as Error)?.message ?? err);
+    if (
+      !/ECONNREFUSED|ENOTFOUND|ETIMEDOUT|EHOSTUNREACH|connect|terminating|password|authentication|role .* does not exist|database .* does not exist/i.test(
+        msg,
+      )
+    ) {
+      throw err;
+    }
+  }
+  msgRepo = new AiChatMessageRepo(db as never);
+  runRepo = new AiChatRunRepo(db as never);
+});
+
+afterAll(async () => {
+  if (db) {
+    try {
+      await db
+        .deleteFrom('aiChatMessages')
+        .where('workspaceId', '=', workspaceId)
+        .execute();
+      await db
+        .deleteFrom('aiChatRuns')
+        .where('workspaceId', '=', workspaceId)
+        .execute();
+    } catch {
+      /* best-effort cleanup */
+    }
+    await db.destroy();
+  }
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+async function seedMessage(overrides: Record<string, unknown> = {}) {
+  return msgRepo.insert({
+    chatId,
+    workspaceId,
+    userId: null as never,
+    role: 'assistant',
+    content: 'x',
+    status: 'streaming',
+    ...overrides,
+  } as never);
+}
+
+async function dbNow(): Promise<string> {
+  const r = await sql<{ now: Date }>`select now() as now`.execute(db);
+  return r.rows[0].now.toISOString();
+}
+
+// Fake ONLY the Date object (so in-process `new Date()`/`Date.now()` jump), while
+// leaving every TIMER function real. Faking timers wholesale freezes postgres.js's
+// internal connection/query timers, so the awaited DB round-trip would hang the
+// test (and the afterAll cleanup) at the jest 5s cap. With Date-only faking the
+// query resolves normally, and we still prove the stamp is the DB clock (not the
+// skewed process clock).
+function fakeDateOnly(iso: string): void {
+  jest.useFakeTimers({
+    doNotFake: [
+      'hrtime',
+      'nextTick',
+      'performance',
+      'queueMicrotask',
+      'requestAnimationFrame',
+      'cancelAnimationFrame',
+      'requestIdleCallback',
+      'cancelIdleCallback',
+      'setImmediate',
+      'clearImmediate',
+      'setInterval',
+      'clearInterval',
+      'setTimeout',
+      'clearTimeout',
+    ],
+    now: new Date(iso),
+  });
+}
+
+const maybe = (name: string, fn: () => Promise<void>) =>
+  it(name, async () => {
+    if (!reachable) {
+      console.warn(`SKIP (${name}): test DB unreachable at ${CONN}`);
+      return;
+    }
+    await fn();
+  });
+
+describe('AiChatMessageRepo.findByChatUpdatedAfter (#491 delta poll)', () => {
+  maybe('null cursor returns no rows and a fresh DB-clock cursor', async () => {
+    const before = await dbNow();
+    const { rows, cursor } = await msgRepo.findByChatUpdatedAfter(
+      chatId,
+      workspaceId,
+      null,
+    );
+    expect(rows).toEqual([]);
+    expect(new Date(cursor).getTime()).toBeGreaterThanOrEqual(
+      new Date(before).getTime(),
+    );
+  });
+
+  maybe('returns only rows changed after the cursor', async () => {
+    const { cursor: c0 } = await msgRepo.findByChatUpdatedAfter(
+      chatId,
+      workspaceId,
+      null,
+    );
+    const m = await seedMessage();
+    const { rows, cursor: c1 } = await msgRepo.findByChatUpdatedAfter(
+      chatId,
+      workspaceId,
+      c0,
+    );
+    expect(rows.map((r) => r.id)).toContain(m.id);
+    // Cursor is monotonic (advances).
+    expect(new Date(c1).getTime()).toBeGreaterThanOrEqual(
+      new Date(c0).getTime(),
+    );
+  });
+
+  maybe(
+    'RACE: a row stamped BEFORE the cursor but seen after is caught by the overlap',
+    async () => {
+      // Cursor taken now; then a row appears whose updatedAt is 2s in the PAST
+      // (committed late on another connection but stamped earlier). A naive
+      // `updatedAt > cursor` would MISS it; the 5s overlap window catches it.
+      const cursor = await dbNow();
+      const m = await seedMessage();
+      await sql`update ai_chat_messages set updated_at = now() - interval '2 seconds' where id = ${m.id}`.execute(
+        db,
+      );
+      const { rows } = await msgRepo.findByChatUpdatedAfter(
+        chatId,
+        workspaceId,
+        cursor,
+      );
+      expect(rows.map((r) => r.id)).toContain(m.id);
+    },
+  );
+
+  maybe(
+    'overlap GUARANTEES repeats across close polls (idempotent-merge contract)',
+    async () => {
+      const { cursor: c0 } = await msgRepo.findByChatUpdatedAfter(
+        chatId,
+        workspaceId,
+        null,
+      );
+      const m = await seedMessage();
+      const first = await msgRepo.findByChatUpdatedAfter(
+        chatId,
+        workspaceId,
+        c0,
+      );
+      expect(first.rows.map((r) => r.id)).toContain(m.id);
+      // Immediately re-poll with the JUST-returned cursor: the row is still within
+      // the overlap window, so it is returned AGAIN — the client MUST dedupe by id.
+      const second = await msgRepo.findByChatUpdatedAfter(
+        chatId,
+        workspaceId,
+        first.cursor,
+      );
+      expect(second.rows.map((r) => r.id)).toContain(m.id);
+    },
+  );
+
+  maybe(
+    'update() stamps updatedAt from the DB clock, not the app clock',
+    async () => {
+      const m = await seedMessage();
+      // Skew the PROCESS clock ~73 years into the future (Date only). If the stamp
+      // came from `new Date()` the row would read year 2099; sql now() keeps it on
+      // DB time.
+      fakeDateOnly('2099-01-01T00:00:00Z');
+      const updated = await msgRepo.update(m.id, workspaceId, {
+        content: 'y',
+      });
+      jest.useRealTimers();
+      expect(updated).toBeDefined();
+      expect(new Date(updated!.updatedAt).getFullYear()).toBeLessThan(2099);
+    },
+  );
+
+  maybe(
+    'run update() also stamps updatedAt from the DB clock',
+    async () => {
+      const run = await runRepo.insert({
+        chatId,
+        workspaceId,
+        createdBy: null as never,
+        trigger: 'user',
+        status: 'running',
+        stepCount: 0,
+      } as never);
+      fakeDateOnly('2099-01-01T00:00:00Z');
+      const updated = await runRepo.update(run.id, workspaceId, {
+        stepCount: 1,
+      });
+      jest.useRealTimers();
+      expect(updated).toBeDefined();
+      expect(new Date(updated!.updatedAt).getFullYear()).toBeLessThan(2099);
+    },
+  );
+});

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

@@ -25,6 +25,20 @@ const SWEEP_STREAMING_STALE_MS = 10 * 60 * 1000; // 10 minutes
 // into memory; far above any realistic transcript length.
 const FIND_ALL_BY_CHAT_LIMIT = 5000;
 
+// Delta-poll overlap (#491): the poll query reaches this far BEHIND the client's
+// echoed cursor, so a row that committed with an `updatedAt` marginally before the
+// previous cursor was taken (on another autocommit connection) is still caught.
+// Sized well above realistic single-row commit skew; the client merge is
+// idempotent by id (mergeById), so the guaranteed repeats the overlap produces are
+// harmless.
+export const DELTA_POLL_OVERLAP_SECONDS = 5;
+
+// Hard cap on rows one delta poll returns — a safety bound (a poll should carry a
+// handful of just-changed rows, never a whole transcript). Ordered by (updatedAt,
+// id) asc, so on the pathological overflow the OLDEST changes win and the newest
+// are picked up by the next poll (its cursor did not advance past them).
+export const DELTA_POLL_MAX_ROWS = 500;
+
 @Injectable()
 export class AiChatMessageRepo {
   private readonly logger = new Logger(AiChatMessageRepo.name);
@@ -139,6 +153,72 @@ export class AiChatMessageRepo {
       .executeTakeFirst();
   }
 
+  /**
+   * Delta read (#491) for the degraded poll: the chat's messages whose row
+   * changed AFTER the client's `cursor`, plus a FRESH cursor taken from the DB
+   * clock. Replaces the old "refetch ALL infinite-query pages every 2.5s with
+   * full parts" poll — the client seeds once (findByChat) and thereafter pulls
+   * only the deltas and merges them by id (mergeById).
+   *
+   * Cursor: a DB-clock timestamp (now()) the client echoes back each poll. All
+   * delta-relevant writes stamp `updatedAt` with now() (see `update` /
+   * `finalizeOwner`), so this is a SINGLE monotonic axis. The query overlaps the
+   * cursor by DELTA_POLL_OVERLAP_SECONDS to catch a row committed with an
+   * `updatedAt` marginally BEFORE the previous cursor was taken on another
+   * connection (single-row autocommit UPDATEs; no long transactions). The overlap
+   * GUARANTEES occasional REPEATS, so the client merge MUST be idempotent by id.
+   *
+   * `cursor === null` (first poll after the full seed) returns NO rows — there is
+   * nothing "new" relative to a just-loaded seed — only the fresh cursor to start
+   * the delta chain. The fresh cursor is read AFTER the rows, so it is >= every
+   * returned row's `updatedAt` (they were read strictly earlier) — a row that
+   * commits between the rows-read and the cursor-read is at most
+   * DELTA_POLL_OVERLAP_SECONDS behind the returned cursor, so the next poll's
+   * overlap window always re-includes it (no miss).
+   */
+  async findByChatUpdatedAfter(
+    chatId: string,
+    workspaceId: string,
+    cursor: string | null,
+  ): Promise<{ rows: AiChatMessage[]; cursor: string }> {
+    if (cursor === null) {
+      const nowRow = await sql<{ now: Date }>`select now() as now`.execute(
+        this.db,
+      );
+      return { rows: [], cursor: nowRow.rows[0].now.toISOString() };
+    }
+    // Overlap the client cursor by DELTA_POLL_OVERLAP_SECONDS, computed in SQL off
+    // the echoed cursor so the whole comparison stays on the DB clock.
+    const rows = await this.db
+      .selectFrom('aiChatMessages')
+      .select(this.baseFields)
+      .where('chatId', '=', chatId)
+      .where('workspaceId', '=', workspaceId)
+      .where('deletedAt', 'is', null)
+      .where(
+        'updatedAt',
+        '>',
+        sql<Date>`${cursor}::timestamptz - make_interval(secs => ${DELTA_POLL_OVERLAP_SECONDS})`,
+      )
+      .orderBy('updatedAt', 'asc')
+      .orderBy('id', 'asc')
+      .limit(DELTA_POLL_MAX_ROWS)
+      .execute();
+    // When the page filled (pathological overflow), DO NOT advance the cursor to
+    // now(): that would skip the changed rows past the cap that this poll did not
+    // return. Resume from the last returned row's updatedAt instead (the next
+    // poll's overlap re-includes ties by id). In the normal case the fresh DB-clock
+    // now() is the cursor.
+    if (rows.length === DELTA_POLL_MAX_ROWS) {
+      return {
+        rows,
+        cursor: rows[rows.length - 1].updatedAt.toISOString(),
+      };
+    }
+    const nowRow = await sql<{ now: Date }>`select now() as now`.execute(this.db);
+    return { rows, cursor: nowRow.rows[0].now.toISOString() };
+  }
+
   async insert(
     insertable: InsertableAiChatMessage,
     trx?: KyselyTransaction,
@@ -172,7 +252,13 @@ export class AiChatMessageRepo {
     const db = dbOrTx(this.db, opts?.trx);
     let query = db
       .updateTable('aiChatMessages')
-      .set({ ...(patch as Record<string, unknown>), updatedAt: new Date() })
+      // #491: stamp `updatedAt` from the DB clock (sql now()), NOT the app clock
+      // (new Date()). The delta-poll cursor (findByChatUpdatedAfter) is a single
+      // DB-clock axis; a per-step 'streaming' UPDATE stamped with the app clock
+      // would be a SECOND, skewed clock source and could leave a row's updatedAt
+      // just under a cursor taken from now() on another connection — an
+      // independent source of delta MISSES. All delta-relevant writes use now().
+      .set({ ...(patch as Record<string, unknown>), updatedAt: sql`now()` })
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId);
     // Concurrency guard (#183 review): a per-step 'streaming' update must NEVER
@@ -214,7 +300,9 @@ export class AiChatMessageRepo {
     const db = dbOrTx(this.db, trx);
     return db
       .updateTable('aiChatMessages')
-      .set({ ...(patch as Record<string, unknown>), updatedAt: new Date() })
+      // #491: DB-clock stamp (see `update`) — this terminal write flips the row's
+      // status, which the delta poll must observe on the shared now() cursor axis.
+      .set({ ...(patch as Record<string, unknown>), updatedAt: sql`now()` })
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
       .where((eb) =>
@@ -249,7 +337,9 @@ export class AiChatMessageRepo {
       .set({
         status,
         metadata: sql`coalesce(metadata, '{}'::jsonb) || jsonb_build_object('finalizeFailed', true)`,
-        updatedAt: new Date(),
+        // #491: DB-clock stamp (see `update`) so a reconcile status flip lands on
+        // the same now() cursor axis the delta poll reads.
+        updatedAt: sql`now()`,
       })
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
@@ -307,7 +397,9 @@ export class AiChatMessageRepo {
       .set({
         status: 'aborted',
         metadata: sql`coalesce(m.metadata, '{}'::jsonb) || jsonb_build_object('finalizeFailed', true)`,
-        updatedAt: new Date(),
+        // #491: DB-clock stamp (see `update`). The staleness WHERE below stays on
+        // the app clock — a >minutes window makes the ms-scale skew irrelevant.
+        updatedAt: sql`now()`,
       })
       .where('m.status', '=', 'streaming')
       .where('m.updatedAt', '<', staleBefore)
@@ -351,7 +443,8 @@ export class AiChatMessageRepo {
       .set({
         status: 'aborted',
         metadata: sql`coalesce(metadata, '{}'::jsonb) || jsonb_build_object('finalizeFailed', true)`,
-        updatedAt: new Date(),
+        // #491: DB-clock stamp (see `update`). Staleness WHERE stays app-clock.
+        updatedAt: sql`now()`,
       })
       .where('status', '=', 'streaming')
       .where('updatedAt', '<', staleBefore)

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

@@ -62,10 +62,17 @@ describe('AiChatRunRepo.sweepRunning', () => {
     // ...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 flips to 'aborted' and stamps finishedAt + updatedAt. #491: the stamps
+    // are now DB-clock `sql now()` expressions (raw builders), NOT app-clock
+    // `new Date()`, so the run row shares the delta poll's single now() cursor axis
+    // — assert they are present and are the sql raw-builder objects (not a Date,
+    // not undefined).
+    expect(rec.set?.status).toBe('aborted');
+    for (const stamp of ['finishedAt', 'updatedAt'] as const) {
+      expect(rec.set?.[stamp]).toBeDefined();
+      expect(rec.set?.[stamp]).not.toBeInstanceOf(Date);
+      expect(typeof rec.set?.[stamp]).toBe('object');
+    }
   });
 
   it('phase-2 path: an explicit staleMs reintroduces the updatedAt window', async () => {

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

@@ -136,7 +136,11 @@ export class AiChatRunRepo {
     const db = dbOrTx(this.db, trx);
     return db
       .updateTable('aiChatRuns')
-      .set({ ...(patch as Record<string, unknown>), updatedAt: new Date() })
+      // #491: DB-clock stamp (sql now()) so the run row shares the delta poll's
+      // single now() cursor axis with the assistant message rows — a run-status
+      // change (the run fact the delta carries) must never sit on a skewed app
+      // clock relative to the message updatedAt cursor.
+      .set({ ...(patch as Record<string, unknown>), updatedAt: sql`now()` })
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
       .returning(this.baseFields)
@@ -162,14 +166,15 @@ export class AiChatRunRepo {
     trx?: KyselyTransaction,
   ): Promise<AiChatRun | undefined> {
     const db = dbOrTx(this.db, trx);
-    const now = new Date();
     return db
       .updateTable('aiChatRuns')
       .set({
         status: patch.status,
         error: patch.error,
-        finishedAt: now,
-        updatedAt: now,
+        // #491: DB-clock stamps (finished_at + updated_at) so the terminal run
+        // fact lands on the delta poll's now() cursor axis.
+        finishedAt: sql`now()`,
+        updatedAt: sql`now()`,
       })
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
@@ -192,7 +197,8 @@ export class AiChatRunRepo {
     const db = dbOrTx(this.db, trx);
     return db
       .updateTable('aiChatRuns')
-      .set({ stopRequestedAt: new Date(), updatedAt: new Date() })
+      // #491: DB-clock stamps (see `update`).
+      .set({ stopRequestedAt: sql`now()`, updatedAt: sql`now()` })
       .where('id', '=', id)
       .where('workspaceId', '=', workspaceId)
       .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[])
@@ -249,13 +255,14 @@ export class AiChatRunRepo {
     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,
+        // #491: DB-clock stamps (see `update`). The staleness WHERE below stays on
+        // the app clock — a >minutes window makes the ms-scale skew irrelevant.
+        finishedAt: sql`now()`,
+        updatedAt: sql`now()`,
         error: sql`coalesce(error, ${'Run interrupted by a server restart.'})`,
       })
       .where('status', 'in', ACTIVE_RUN_STATUSES as unknown as string[]);
@@ -263,7 +270,7 @@ export class AiChatRunRepo {
     // 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);
+      const staleBefore = new Date(Date.now() - opts.staleMs);
       query = query.where('updatedAt', '<', staleBefore);
     }
     const rows = await query.returning('id').execute();

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

@@ -606,6 +606,9 @@ export interface AiChats {
   // The document the chat was created in (open page at first message). NULL =>
   // started outside any document. ON DELETE SET NULL on the page FK.
   pageId: string | null;
+  // Chat-level metadata bag (#490). jsonb, defaulted to '{}'. First key:
+  // `activatedTools` — the deferred-tool activation set persisted across turns.
+  metadata: Generated<Json>;
   createdAt: Generated<Timestamp>;
   updatedAt: Generated<Timestamp>;
   deletedAt: Timestamp | null;

apps/server/src/integrations/ai/ai-settings.service.ts

@@ -245,6 +245,9 @@ export class AiSettingsService {
       // Max context window for the chat header badge denominator. Stored as
       // ::text; 0/unset/invalid = no limit (undefined).
       chatContextWindow: parsePositiveInt(provider.chatContextWindow),
+      // RAW stored value (#490): the replay budgeter reads this to distinguish an
+      // explicit `0` (off-switch) from unset, which parsePositiveInt cannot.
+      chatContextWindowRaw: provider.chatContextWindow,
       // Plain passthrough; getChatModel defaults unset to 'openai-compatible'.
       chatApiStyle: provider.chatApiStyle,
       // Cheap model id for the anonymous public-share assistant; reuses the chat

apps/server/src/integrations/ai/ai.types.ts

@@ -105,6 +105,10 @@ export interface ResolvedAiConfig extends Partial<AiProviderSettings> {
   // Max context window in tokens; surfaced to the chat header badge as the
   // "current / max" denominator. 0/unset = no limit.
   chatContextWindow?: number;
+  // RAW stored context window (::text), BEFORE parsePositiveInt collapses `0` and
+  // unset to `undefined`. The #490 replay budgeter needs the raw value to honor an
+  // explicit `0` off-switch distinctly from "unset -> flat default".
+  chatContextWindowRaw?: string | number;
   // Cheap model id for the public-share assistant; reuses the chat creds.
   publicShareChatModel?: string;
   // Agent-role id whose persona the public-share assistant adopts (empty/unset

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

@@ -30,11 +30,13 @@ import {
  * tees the SSE frames into it via `consumeSseStream` while stamping the DB row id
  * via `generateMessageId` (both gated on runId + the resumable flag).
  *
- * Proven here: a finished run's replay is the full frame sequence incl `[DONE]`
- * with `start.messageId` == the seeded DB row id; the anchor check (invariant 6);
- * an attach opened BEFORE the first frame follows the live stream from frame 0; an
- * explicit stop surfaces `{"type":"abort"}` + `[DONE]` + end to the subscriber;
- * and the legacy (non-run) path tees nothing.
+ * Proven here (tail-only #491): a finished run attached at its persisted frontier
+ * N_final delivers only the TAIL past N (a synthetic `start` carrying the run-fact
+ * + the terminal `finish`/`[DONE]`) — the step content below N lives in the seeded
+ * DB row, NOT the ring; the anchor check (invariant 6); an attach opened BEFORE the
+ * first frame follows the live stream from frame 0; an explicit stop surfaces
+ * `{"type":"abort"}` + `[DONE]` + end to the subscriber; and the legacy (non-run)
+ * path tees nothing.
  */
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
@@ -133,14 +135,16 @@ function liveSink(): {
   };
 }
 
-// The SSE `start` frame carries the message id; pull it out of a `data: {...}`.
-function parseStartMessageId(frames: string[]): string | undefined {
+// Parse the first `start` frame's JSON out of a `data: {...}` sequence.
+function parseStartFrame(
+  frames: string[],
+): { messageId?: string; messageMetadata?: any } | undefined {
   for (const f of frames) {
     const m = /^data: (\{.*\})\s*$/m.exec(f.trim());
     if (!m) continue;
     try {
       const json = JSON.parse(m[1]);
-      if (json.type === 'start') return json.messageId;
+      if (json.type === 'start') return json;
     } catch {
       /* not this frame */
     }
@@ -270,7 +274,7 @@ describe('AiChatService run-stream attach [integration]', () => {
     await destroyTestDb();
   });
 
-  it('run-wrapped: replay is the full frame sequence incl [DONE], start.messageId == the seeded DB row id', async () => {
+  it('run-wrapped, tail-only: a finished run at N_final delivers the run-fact start + finish/[DONE]; the step content lives in the seeded row', async () => {
     const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
     const registry = new AiChatStreamRegistryService();
     const runService = new AiChatRunService(runRepo, {
@@ -300,27 +304,37 @@ describe('AiChatService run-stream attach [integration]', () => {
         );
       });
       const rowId = await assistantRowId(chatId);
+      // The client reads its persisted step frontier N from the seeded row.
+      const row: any = await msgRepo.findById(rowId, workspaceId);
+      const nFinal = row.metadata.stepsPersisted as number;
+      expect(nFinal).toBe(1); // a single finished step
+      // The step content is in the SEEDED row (parts/content), not the ring.
+      expect(JSON.stringify(row.metadata.parts)).toContain('Hello');
 
-      // Finished-run replay with expect=live + the correct anchor.
+      // Attach at N_final with the correct anchor: the tail past step 1 is just
+      // the terminal frames; step 0's 'Hello' is BELOW the frontier (seeded).
       const sink = liveSink();
-      const att = await registry.attach(chatId, true, rowId, sink.cb);
+      const att = await registry.attach(chatId, rowId, nFinal, sink.cb);
       expect(att).not.toBeNull();
       expect(att!.finished).toBe(true);
-      // The tee captured frames (consumeSseStream was wired).
-      expect(att!.replay.length).toBeGreaterThan(0);
-      // generateMessageId stamped the DB row id onto the streamed start frame.
-      expect(parseStartMessageId(att!.replay)).toBe(rowId);
-      // The full sequence includes the streamed text and the terminal marker.
-      const joined = att!.replay.join('');
-      expect(joined).toContain('Hello');
+      // The synthetic start frame carries the run-fact (runId/chatId), the source
+      // of the run-fact on re-attach.
+      const start = parseStartFrame(att!.replay);
+      expect(start?.messageMetadata).toMatchObject({
+        runId: box.runId,
+        chatId,
+      });
+      // The terminal marker is delivered so the client's SDK closes the stream.
       expect(att!.replay.some((f) => f.includes('[DONE]'))).toBe(true);
+      // 'Hello' (step 0, below the frontier) is NOT re-streamed — it is seeded.
+      expect(att!.replay.some((f) => f.includes('Hello'))).toBe(false);
     } finally {
       registry.onModuleDestroy();
       await cleanup();
     }
   });
 
-  it('anchor mismatch with expect=live returns null (invariant 6)', async () => {
+  it('anchor mismatch returns null (invariant 6)', async () => {
     const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
     const registry = new AiChatStreamRegistryService();
     const runService = new AiChatRunService(runRepo, {
@@ -347,7 +361,7 @@ describe('AiChatService run-stream attach [integration]', () => {
       const sink = liveSink();
       // A foreign anchor must NOT replay this run's transcript.
       expect(
-        await registry.attach(chatId, true, 'a-different-run-row', sink.cb),
+        await registry.attach(chatId, 'a-different-run-row', 1, sink.cb),
       ).toBeNull();
     } finally {
       registry.onModuleDestroy();
@@ -376,8 +390,11 @@ describe('AiChatService run-stream attach [integration]', () => {
     try {
       // Attach while the entry exists (opened at begin) but before any frame.
       const sink = liveSink();
-      const att = (await registry.attach(chatId, false, undefined, sink.cb))!;
-      expect(att.replay).toEqual([]); // nothing streamed yet -> replay from 0
+      const att = (await registry.attach(chatId, undefined, 0, sink.cb))!;
+      // Nothing streamed yet -> the tail is just the synthetic start frame; the
+      // whole live stream (start..DONE) follows via onFrame after start().
+      expect(att.replay).toHaveLength(1);
+      expect(att.replay[0]).toContain('"type":"start"');
       att.start(); // go live (drains nothing, then follows)
 
       // Now emit the whole turn.
@@ -448,7 +465,7 @@ describe('AiChatService run-stream attach [integration]', () => {
     });
     try {
       const sink = liveSink();
-      const att = (await registry.attach(chatId, false, undefined, sink.cb))!;
+      const att = (await registry.attach(chatId, undefined, 0, sink.cb))!;
       att.start();
 
       // Give streamText a beat to begin consuming the partial output.
@@ -526,7 +543,9 @@ describe('AiChatService run-stream attach [integration]', () => {
       expect(entry).toBeDefined();
       expect(entry.finished).toBe(true);
       const sink = liveSink();
-      expect(await registry.attach(chatId, false, undefined, sink.cb)).toBeNull();
+      // Finished with an EMPTY ring (aborted before any frame) -> null -> the
+      // client degrades to poll instead of hanging on an empty stream.
+      expect(await registry.attach(chatId, undefined, 0, sink.cb)).toBeNull();
     } finally {
       registry.onModuleDestroy();
       await cleanup();
@@ -556,8 +575,8 @@ describe('AiChatService run-stream attach [integration]', () => {
       });
       const sink = liveSink();
       // No entry was ever opened; attach always yields null.
-      expect(await registry.attach(chatId, false, undefined, sink.cb)).toBeNull();
-      expect(await registry.attach(chatId, true, 'anything', sink.cb)).toBeNull();
+      expect(await registry.attach(chatId, undefined, 0, sink.cb)).toBeNull();
+      expect(await registry.attach(chatId, 'anything', 1, sink.cb)).toBeNull();
     } finally {
       registry.onModuleDestroy();
       await cleanup();

apps/server/test/jest-integration.json

@@ -22,6 +22,7 @@
     "^@docmost/db/(.*)$": "<rootDir>/src/database/$1",
     "^@docmost/transactional/(.*)$": "<rootDir>/src/integrations/transactional/$1",
     "^@docmost/ee/(.*)$": "<rootDir>/src/ee/$1",
+    "^@docmost/token-estimate$": "<rootDir>/../../packages/token-estimate/src/index.ts",
     "^src/(.*)$": "<rootDir>/src/$1"
   }
 }

docs/reading-ai-logs.md

@@ -8,19 +8,35 @@ real pain (a "which tools fail most?" analysis that confidently answered
 
 Read the **Gotchas** section before you trust any error count.
 
+> **TWO ERAS — check the marker first.** The `tool_calls` shape changed in **#490
+> (trace v2)**. A row written by v2 carries `metadata.toolTraceVersion = 2`; older
+> rows have no such key. The two shapes store DIFFERENT things (v2 dropped the tool
+> OUTPUT from the trace), so **every query below is dual-shape** — branch on the
+> marker. **Never compare an aggregate or trend across the era boundary**: a metric
+> jump on the cut-over week is an artifact of the shape change, not a behavior
+> change.
+
 ## TL;DR
 
 - Agent chats live in Postgres, DB `docmost`, tables `ai_chat_*`.
-- Each tool invocation is stored as **two** array elements (a `tool-call` part and
-  a `tool-result` part), so naive counting double-counts.
-- **A tool that *throws* writes no result part.** Since the #407 fix its error is
-  persisted as a dedicated `{toolName, error}` element in `tool_calls` (queryable +
-  replayed to the model). **Rows written before #407 still drop it** — the error is
-  nowhere in the DB and shows only in the live UI. So `isError` / `success=false`
-  scans under-report by design, and pre-#407 thrown errors are invisible.
-- To find where agents fail: (1) soft-failure markers in `tool_calls`, (2) the new
-  `error` field for thrown errors (new rows) / the orphan-gap proxy (old rows),
-  (3) server logs / the live UI for full stack traces beyond the truncated message.
+- **Era marker:** `metadata.toolTraceVersion = 2` ⇒ v2 (#490) row; absent ⇒ legacy row.
+- Each tool invocation is stored as **two** consecutive array elements — a
+  `tool-call` part then an OUTCOME part — so naive counting double-counts.
+  - **v2 (#490):** outcome is `{toolName, ok: true}` on success, or
+    `{toolName, error, kind: 'thrown'|'interrupted'}` on failure. The tool **OUTPUT
+    is NOT in `tool_calls`** any more — it lives once in `metadata.parts` (this
+    removed a hundreds-of-MB-per-run write duplication). Soft-failure analysis
+    therefore reads `metadata.parts`, not `tool_calls`.
+  - **legacy:** outcome is `{toolName, output}` on success; a **thrown** failure is
+    a `{toolName, error}` element **only on rows after #407**, and is dropped
+    entirely (silent orphan) on pre-#407 rows.
+- **A tool that *throws* writes no result part.** In v2 it is a
+  `{error, kind:'thrown'}` element; an interrupted/aborted call is a distinct
+  `{error, kind:'interrupted'}`. `isError`/`success=false` scans read the *output*
+  and so under-report thrown failures in every era.
+- To find where agents fail: (1) soft-failure markers in `metadata.parts` outputs
+  (v2) / `tool_calls` outputs (legacy), (2) the `error`/`kind` fields for thrown
+  failures (v2 + post-#407), (3) server logs / the live UI for full stack traces.
 
 ## Where the data lives
 
@@ -53,33 +69,67 @@ are rows in `workspaces`, not separate deployments.
 separate `tool` role), `content` (text), `tool_calls` (jsonb array), `metadata`
 (jsonb, holds run `error` + rendered `parts`), `status`, `tsv` (full-text index).
 
+## Era marker — check this before every query
+
+```sql
+-- how many rows are in each era?
+SELECT COALESCE((metadata->>'toolTraceVersion'), 'legacy') AS era, count(*)
+FROM ai_chat_messages
+WHERE role = 'assistant' AND jsonb_typeof(tool_calls) = 'array'
+GROUP BY 1 ORDER BY 2 DESC;
+```
+
+- `toolTraceVersion = '2'` → **v2** (#490): outcome flags, **no output in the trace**.
+- `NULL` (`'legacy'`) → pre-#490: outcome carries the tool `output` inline.
+
+**Do not trend a metric across the cut-over.** The shape change alone shifts counts
+(e.g. "elements with `output`" collapses to zero for v2), so a week that straddles
+the boundary shows an artifact, not a behavior change. Segment by era, or restrict to
+one era, before comparing.
+
 ## How tool calls are stored — READ THIS
 
 Tool calls are **not** one-object-per-call. Each logical invocation is split into
-two consecutive elements of the `tool_calls` array:
+two consecutive elements of the `tool_calls` array — a **call** then an **outcome**.
+The outcome shape is era-dependent:
 
 ```text
-index 0: { "toolName": "getPage",  "input":  { "pageId": "…" } }   ← tool-call   (has input, NO output)
-index 1: { "toolName": "getPage",  "output": { … } }                ← tool-result (has output, NO input)
+# v2 (#490) — metadata.toolTraceVersion = 2
+index 0: { "toolName":"getPage", "input":{...} }                       ← call     (has input)
+index 1: { "toolName":"getPage", "ok":true }                          ← success  (NO output here)
+   or  : { "toolName":"getPage", "error":"…", "kind":"thrown" }       ← threw
+   or  : { "toolName":"getPage", "error":"…", "kind":"interrupted" }  ← aborted mid-step
+
+# legacy — no toolTraceVersion
+index 0: { "toolName":"getPage", "input":{...} }                       ← call     (has input, NO output)
+index 1: { "toolName":"getPage", "output":{...} }                     ← success  (has output)
+   or  : { "toolName":"getPage", "error":"…" }                        ← threw (post-#407 only)
 ```
 
-The keys that appear on an element are `toolName`, `input`, `output`, and — for a
-**thrown** failure on rows written after the #407 fix — `error` (the tool's error
-message; see the "Hard failures" section below). There is no `state`, no `errorText`,
-no `type`. On pre-#407 rows a thrown failure has NO paired result element at all
-(silent orphan). Consequences:
+The keys that can appear: `toolName`, `input` (call), and on the outcome — **v2:**
+`ok` **or** `error`+`kind`; **legacy:** `output` **or** (post-#407) `error`. There is
+no `state`, no `errorText`, no `type` in `tool_calls` (those live on `metadata.parts`).
+Consequences:
 
-1. **Real invocation count = elements that have `output` or `error`.** Counting every
-   element double-counts (you get ~2× and a spurious "~50% of every tool has no output").
-2. **Pairing:** a call = a `tool-call` part followed by its result part. A success
-   carries `output`; a thrown failure (post-#407) carries `error` instead. Both carry
-   `toolName`, so you can group by tool on either.
+1. **Real invocation count** — count the OUTCOME elements, not every element (else you
+   double-count): **v2** = elements with `ok` or `error`; **legacy** = elements with
+   `output` or `error`.
+2. **Pairing:** a call (`input`) is followed by its outcome. `toolName` is on both, so
+   you can group by tool on either. In v2 the `kind` field separates a real hard-fail
+   (`thrown`) from an aborted call (`interrupted`) — a distinction legacy rows cannot
+   make (both are orphans; see below).
+3. **The tool OUTPUT is only in `metadata.parts` on v2 rows.** To inspect what a tool
+   returned (soft-error markers, page bodies) on a v2 row, read the parts
+   (`part->>'type' LIKE 'tool-%'`, `part->>'state' = 'output-available'`, `part->'output'`),
+   not `tool_calls`.
 
 ## The two classes of failure (and which the DB can see)
 
 ### 1. Soft failures — tool RAN and returned an error-shaped result → PERSISTED ✅
 
-These are visible in the `tool-result` `output`. The marker differs per tool:
+These are visible in the tool `output` — **on v2 rows in `metadata.parts`** (the
+`output-available` part's `output`), on **legacy rows in the `tool_calls` outcome
+element's `output`**. The marker differs per tool:
 
 | Tool(s) | Error marker in `output` |
 | --- | --- |
@@ -91,37 +141,32 @@ These are visible in the `tool-result` `output`. The marker differs per tool:
 Note `editPageText` returns `failed: []` on success — filtering on the *presence*
 of the key gives false positives; filter on **non-empty**.
 
-### 2. Hard failures — tool THREW → NOW PERSISTED ✅ (since the #407 fix)
+### 2. Hard failures — tool THREW → PERSISTED ✅
 
 When a tool throws (the classic one is `patchNode` / `insertNode` / `tableUpdateCell`
 → `Failed to encode document to Yjs (fromJSON): Unknown node type: undefined`), the
-runtime still writes **no `tool-result` part** — the failure is an ai@6 `tool-error`
-content part instead. **Since the #407 fix, that error is persisted**: `serializeSteps`
-appends a dedicated element `{toolName, error: "<message>"}` right after the failed
-call, mirroring how a successful `{toolName, output}` element is appended. So a thrown
-error now leaves a queryable `error` field carrying its (truncated) reason, and the
-same real text is replayed to the model on the next turn (an `output-error` part with
-the real `errorText`, no longer the `'Tool call did not complete.'` placeholder).
+runtime writes **no `tool-result` part** — the failure is an ai@6 `tool-error` content
+part. How that lands in `tool_calls` depends on the era:
 
-**Cutover caveat — old rows keep the old blind shape.** Rows written **before** this
-change have the two-part shape (`call` + `output` only) and simply **drop** thrown
-errors, leaving a silent **orphan** (a `call` with no `output` *and* no `error`). Rows
-written **after** the fix additionally carry the `error` element. So:
+- **v2 (#490):** a `{toolName, error, kind:'thrown'}` outcome element. An interrupted /
+  aborted mid-step call is a **distinct** `{toolName, error:'Tool call did not
+  complete.', kind:'interrupted'}` element — so you can tell a real hard-fail from an
+  abort **directly, without the orphan heuristic**. Query `kind = 'thrown'`.
+- **post-#407 legacy:** a `{toolName, error}` element (no `kind`) right after the call.
+- **pre-#407 legacy:** the error is **dropped** — a silent **orphan** (a `call` with no
+  `output` *and* no `error`).
 
-- **New rows:** query the `error` field directly (see the hard-error query below) — no
-  orphan heuristic needed for thrown failures.
-- **Old rows (pre-#407):** the only DB-side proxy is still an **orphan**: a `tool-call`
-  part with no matching `tool-result` *and* no `error`. Orphans also appear when a run
-  is **aborted** mid-flight (server restart), so a high-volume tool (`createComment`,
-  `searchInPage`, `Search_web_search`) shows orphans from aborts, not real errors on
-  old rows. Treat the orphan gap as an *upper bound*, and cross-check the tool: a gap on
-  a structural editor (`patchNode`, `insertNode`, `updatePageJson`, `transformPage`) is
-  almost certainly a thrown Yjs-encode error; a gap on `createComment` is mostly aborts.
+The same real error text is replayed to the model on the next turn (an `output-error`
+part with the real `errorText`, from `metadata.parts`), in every era.
 
-A note on the aborted-call fallback: a call with **neither** a result **nor** a
-`tool-error` (genuinely interrupted mid-step) still replays with the
-`'Tool call did not complete.'` placeholder and persists as an orphan — that path is
-unchanged, and is distinct from a real thrown error, which now carries `error`.
+**Cutover caveat.** Only pre-#407 legacy rows need the orphan proxy: an orphan is a
+`tool-call` with no matching outcome. Orphans there also appear when a run is **aborted**
+mid-flight (server restart), so a high-volume tool (`createComment`, `searchInPage`,
+`Search_web_search`) shows orphans from aborts, not real errors. Treat the orphan gap as
+an *upper bound* and cross-check the tool: a gap on a structural editor (`patchNode`,
+`insertNode`, `updatePageJson`, `transformPage`) is almost certainly a thrown Yjs-encode
+error; a gap on `createComment` is mostly aborts. **On v2 rows this ambiguity is gone**
+— `kind` labels each outcome.
 
 ### 3. Run-level failures → `ai_chat_runs`
 
@@ -134,22 +179,34 @@ the wild: `Run interrupted by a server restart.` (aborts) and
 
 Run all of these via `docker exec gitmost-postgresql psql -U docmost -d docmost -P pager=off -c "…"`.
 
-**Real invocation count per tool** (result parts only — the correct denominator):
+**Real invocation count per tool** (outcome parts only — the correct denominator).
+Dual-shape: a v2 outcome has `ok` or `error`; a legacy outcome has `output` or `error`:
 
 ```sql
 SELECT elem->>'toolName' AS tool, count(*) AS calls
 FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
-WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
+WHERE jsonb_typeof(m.tool_calls) = 'array'
+  AND (elem ? 'ok' OR elem ? 'output' OR elem ? 'error')
 GROUP BY 1 ORDER BY 2 DESC;
 ```
 
-**Soft errors per tool** (everything the DB can honestly see):
+**Soft errors per tool.** The soft-error marker lives in the tool OUTPUT — which on
+**v2 rows is in `metadata.parts`**, on **legacy rows is in the `tool_calls` outcome
+element**. This query UNIONs both eras, projecting each output as `o`:
 
 ```sql
 WITH res AS (
+  -- v2 (#490): output is in metadata.parts (output-available tool parts)
+  SELECT part->>'type' AS tool, part->'output' AS o
+  FROM ai_chat_messages m, jsonb_array_elements(m.metadata->'parts') part
+  WHERE (m.metadata->>'toolTraceVersion') = '2'
+    AND part->>'type' LIKE 'tool-%' AND part->>'state' = 'output-available'
+  UNION ALL
+  -- legacy: output is inline in the tool_calls outcome element
   SELECT elem->>'toolName' AS tool, elem->'output' AS o
   FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
-  WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
+  WHERE (m.metadata->>'toolTraceVersion') IS NULL
+    AND jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
 )
 SELECT tool, count(*) AS calls,
        sum(COALESCE(
@@ -167,13 +224,23 @@ FROM res GROUP BY tool HAVING sum(COALESCE(
 ORDER BY soft_errors DESC;
 ```
 
-**`editPageText` failure reasons** (the most common real agent mistake — bad `find`):
+Note the v2 `tool` label is the part type (`tool-editPageText`); strip the `tool-`
+prefix if you join it against the legacy `toolName`.
+
+**`editPageText` failure reasons** (the most common real agent mistake — bad `find`).
+Same dual-shape output source:
 
 ```sql
 WITH res AS (
+  SELECT part->'output' AS o
+  FROM ai_chat_messages m, jsonb_array_elements(m.metadata->'parts') part
+  WHERE (m.metadata->>'toolTraceVersion') = '2'
+    AND part->>'type' = 'tool-editPageText' AND part->>'state' = 'output-available'
+  UNION ALL
   SELECT elem->'output' AS o
   FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
-  WHERE jsonb_typeof(m.tool_calls) = 'array'
+  WHERE (m.metadata->>'toolTraceVersion') IS NULL
+    AND jsonb_typeof(m.tool_calls) = 'array'
     AND elem->>'toolName' = 'editPageText' AND elem ? 'output'
 )
 SELECT f->>'reason' AS reason, count(*)
@@ -182,30 +249,43 @@ WHERE jsonb_typeof(o->'failed') = 'array'
 GROUP BY 1 ORDER BY 2 DESC;
 ```
 
-**Hard errors — persisted `error` field per tool (NEW rows, since #407)** — thrown
-tool failures now carry their real reason, so query them directly:
+**Hard errors — persisted `error` field per tool (v2 + post-#407 rows)** — thrown tool
+failures carry their real reason, so query them directly. On **v2** rows exclude the
+`interrupted` kind so an aborted call is not counted as a hard-fail:
 
 ```sql
 SELECT elem->>'toolName' AS tool, count(*) AS thrown_errors,
        min(elem->>'error') AS sample_error
 FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
 WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'error'
+  -- v2 rows label the kind; a legacy error element has no kind (count it).
+  AND COALESCE(elem->>'kind', 'thrown') = 'thrown'
+GROUP BY 1 ORDER BY 2 DESC;
+```
+
+Aborted mid-step calls on v2 rows are a distinct, directly countable population:
+
+```sql
+SELECT elem->>'toolName' AS tool, count(*) AS interrupted
+FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
+WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem->>'kind' = 'interrupted'
 GROUP BY 1 ORDER BY 2 DESC;
 ```
 
 **Hard-error proxy for OLD rows (pre-#407) — orphan gap per tool, WITH a spread column**
-(call parts minus result parts, plus how many distinct chats the gap is spread across).
-This covers rows written before thrown errors were persisted; on new rows a thrown
-failure now has its own `error` element (use the query above) and an orphan means only
-a genuinely aborted mid-step call:
+(call parts minus outcome parts, plus how many distinct chats the gap is spread across).
+This is needed ONLY for pre-#407 legacy rows (v2 and post-#407 rows carry the error /
+`kind` directly — use the queries above). The `WHERE` restricts to the legacy era so v2
+rows (where an `ok` outcome is not an `output`) never produce phantom orphans:
 
 ```sql
 WITH parts AS (
   SELECT m.chat_id, elem->>'toolName' AS tool,
-         (elem ? 'input' AND NOT (elem ? 'output')) AS is_call,
-         (elem ? 'output' OR elem ? 'error')        AS is_result
+         (elem ? 'input' AND NOT (elem ? 'output') AND NOT (elem ? 'ok')) AS is_call,
+         (elem ? 'output' OR elem ? 'error' OR elem ? 'ok')               AS is_result
   FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
   WHERE jsonb_typeof(m.tool_calls) = 'array' AND m.role = 'assistant'
+    AND (m.metadata->>'toolTraceVersion') IS NULL
 ),
 per_chat AS (
   SELECT tool, chat_id, sum(is_call::int) - sum(is_result::int) AS gap
@@ -261,11 +341,21 @@ WHERE tsv @@ websearch_to_tsquery('english', 'some phrase') LIMIT 20;
 
 ## Don't blow up your context
 
-A single `tool_calls` row can be **300–400 KB** (results embed full page content and
-search payloads). Never `SELECT tool_calls` (or `jsonb_pretty(tool_calls)`) raw.
-Always project just the keys you need and truncate:
+Tool outputs embed full page content and search payloads (hundreds of KB per row).
+On **legacy** rows they are in `tool_calls`; on **v2** rows they moved to
+`metadata->'parts'` (the `tool_calls` trace itself is now small). Never `SELECT
+tool_calls` / `metadata` (or `jsonb_pretty(...)`) raw — project just the keys you need
+and truncate:
 
 ```sql
+-- v2: outputs live in metadata.parts
+SELECT part->>'type',
+       left(regexp_replace((part->'output')::text, '\s+', ' ', 'g'), 200)
+FROM ai_chat_messages m, jsonb_array_elements(m.metadata->'parts') part
+WHERE (m.metadata->>'toolTraceVersion') = '2'
+  AND part->>'state' = 'output-available' LIMIT 5;
+
+-- legacy: outputs live in tool_calls
 SELECT elem->>'toolName',
        left(regexp_replace((elem->'output')::text, '\s+', ' ', 'g'), 200)
 FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
@@ -280,26 +370,32 @@ docker compose -p gitmost logs -f --tail=100 # whole stack
 ```
 
 Logging is `json-file`, `max-size=10m max-file=5` → ~50 MB retained, then rotated,
-and **wiped on container recreate**. Since the #407 fix, thrown-tool error text is
-**persisted in the `error` field** of `tool_calls` (see the hard-error query above), so
-you no longer depend on live logs for it. Logs/live UI remain useful for **pre-#407
-rows** (whose thrown errors were dropped) and for full stack traces beyond the
-truncated stored message. A per-tool `tool_calls_total{tool,status}` metric to
-VictoriaMetrics is still a possible future add for aggregate dashboards.
+and **wiped on container recreate**. Thrown-tool error text is **persisted** — in the
+`error` field of `tool_calls` (v2 `kind:'thrown'` / post-#407 legacy) — so you no longer
+depend on live logs for it. Logs/live UI remain useful for **pre-#407 rows** (whose
+thrown errors were dropped) and for full stack traces beyond the truncated stored
+message. A per-tool `tool_calls_total{tool,status}` metric to VictoriaMetrics is still a
+possible future add for aggregate dashboards.
 
 ## Gotchas checklist
 
-- [ ] Counting every `tool_calls` element → **overcount**. Count `output` elements; add `error` elements for thrown failures (new rows), but don't count both as invocations.
-- [ ] `isError` / `success=false` ≈ 0 does **not** mean "no errors" — thrown errors are a separate `error` element (new rows) or dropped entirely (pre-#407 rows).
-- [ ] Thrown errors persist only on rows written **after the #407 fix** — pre-#407 rows still drop them (orphan only). Mind the cutover when trending over time.
+- [ ] **Check `metadata.toolTraceVersion` first.** v2 (`= 2`) has no output in `tool_calls`; legacy has it inline. Never trend a metric across the era boundary.
+- [ ] Counting every `tool_calls` element → **overcount**. Count OUTCOME elements — v2: `ok` or `error`; legacy: `output` or `error` — never both call+outcome as invocations.
+- [ ] `isError` / `success=false` ≈ 0 does **not** mean "no errors" — thrown errors are an `error` element (v2 `kind:'thrown'` / post-#407), not in the output.
+- [ ] **v2:** soft-error markers (the tool output) are in `metadata.parts`, NOT `tool_calls`. Legacy: they are in the `tool_calls` outcome `output`.
+- [ ] **v2:** `kind` splits a real hard-fail (`thrown`) from an aborted call (`interrupted`) directly — no orphan heuristic needed. The orphan gap is a pre-#407-legacy-only proxy.
 - [ ] `editPageText.failed` is `[]` on success — test for **non-empty**, not presence.
-- [ ] Orphan gap on OLD rows mixes thrown errors **and** aborted runs — split by tool. On NEW rows a thrown error is its own `error` element, so a gap ≈ aborted call.
 - [ ] `aborted` runs = server restarts, `failed` runs = provider overload — not agent mistakes.
-- [ ] Never dump a raw `tool_calls` cell — it can be hundreds of KB.
-- [ ] Logs are ephemeral (≤50 MB, wiped on recreate) — grab hard-error text live.
+- [ ] Never dump a raw `tool_calls` **or** `metadata.parts` cell — outputs are hundreds of KB.
+- [ ] Logs are ephemeral (≤50 MB, wiped on recreate) — grab pre-#407 hard-error text live.
 
 ## Snapshot (2026-07-07, illustrative — rerun the queries for current numbers)
 
+> All rows in this snapshot predate #490, so they are **legacy-era** (outputs inline in
+> `tool_calls`, orphan proxy for thrown errors). Do not trend these numbers against v2
+> rows — segment by `toolTraceVersion` first.
+
+
 - 226 chats, 732 messages, 46 runs; ~4 400 real tool invocations.
 - Soft errors (persisted): `editPageText` 4/79 (bad/non-unique `find`) + 9 markdown-in-`find` warnings; `semanticSearch` 3/4 (`unavailable`); `Habr_update_draft_from_docmost` 1/2 (`doc` sent as object, not string).
 - Missing-result proxy, read WITH the spread column:

packages/mcp/src/client/comments.ts

@@ -59,6 +59,39 @@ import {
   mergeFootnoteDefinitions,
 } from "../lib/transforms.js";
 
+// Max concurrent per-page comment fetches in checkNewComments (#490). The scan is
+// O(N) independent REST reads over the working set; running them one-at-a-time made
+// a large space linear in round-trips. A small cap parallelizes without hammering
+// the server (or exhausting sockets). 6 is a conservative middle of the 5–8 band.
+const COMMENT_SCAN_CONCURRENCY = 6;
+
+/**
+ * Map `items` through `fn` with at most `limit` in flight, preserving INPUT ORDER
+ * in the returned array. A tiny bounded pool (no p-limit dependency): `limit`
+ * workers pull the next index off a shared cursor until the list is drained.
+ */
+async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const i = cursor++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  };
+  const workers = Array.from(
+    { length: Math.max(1, Math.min(limit, items.length)) },
+    () => worker(),
+  );
+  await Promise.all(workers);
+  return results;
+}
+
 // Public method surface of CommentsMixin (issue #450) — a NAMED type so the factory
 // return type is expressible in the emitted .d.ts (the anonymous mixin class
 // carries the base's protected shared state, which would otherwise trip TS4094).
@@ -655,27 +688,32 @@ export function CommentsMixin<TBase extends GConstructor<DocmostClientContext>>(
       parentPageId,
     );
 
-    // 2. Fetch comments for each page, keep ones created after since
-    const results: any[] = [];
-    for (const page of pagesInScope) {
-      try {
-        // Full feed (incl. resolved): a "new comments since" scan reports all
-        // recent activity; the active-only filter is scoped to listComments.
-        const comments = (await this.listComments(page.id, true)).items;
-        const newComments = comments.filter(
-          (c: any) => new Date(c.createdAt) > sinceDate,
-        );
-        if (newComments.length > 0) {
-          results.push({
-            pageId: page.id,
-            pageTitle: page.title,
-            comments: newComments,
-          });
+    // 2. Fetch comments for each page, keep ones created after since. Runs with
+    // bounded concurrency (#490) instead of one-at-a-time — the per-page reads are
+    // independent, so a large working set no longer costs O(N) serial round-trips.
+    // Order is preserved (mapWithConcurrency keeps input order), so the output is
+    // deterministic regardless of which fetch finishes first.
+    const perPage = await mapWithConcurrency(
+      pagesInScope,
+      COMMENT_SCAN_CONCURRENCY,
+      async (page: any) => {
+        try {
+          // Full feed (incl. resolved): a "new comments since" scan reports all
+          // recent activity; the active-only filter is scoped to listComments.
+          const comments = (await this.listComments(page.id, true)).items;
+          const newComments = comments.filter(
+            (c: any) => new Date(c.createdAt) > sinceDate,
+          );
+          return newComments.length > 0
+            ? { pageId: page.id, pageTitle: page.title, comments: newComments }
+            : null;
+        } catch (e: any) {
+          // Skip pages with errors (e.g. deleted between calls)
+          return null;
         }
-      } catch (e: any) {
-        // Skip pages with errors (e.g. deleted between calls)
-      }
-    }
+      },
+    );
+    const results: any[] = perPage.filter((r): r is any => r !== null);
 
     const totalNewComments = results.reduce(
       (sum, r) => sum + r.comments.length,

packages/mcp/test/mock/pagination-cursor.test.mjs

@@ -442,3 +442,139 @@ test("checkNewComments subtree includes the root without a separate getPageRaw",
   assert.equal(result.checkedPages, 2, "root + one descendant scanned");
   assert.equal(result.totalNewComments, 1, "the root's fresh comment found");
 });
+
+// -----------------------------------------------------------------------------
+// 6) checkNewComments parallelism (#490): the per-page comment fetches run with
+//    bounded concurrency (not one-at-a-time), and the results still preserve the
+//    page order deterministically regardless of which fetch finishes first.
+// -----------------------------------------------------------------------------
+test("checkNewComments fetches pages concurrently (bounded) and preserves order", async () => {
+  // A subtree with 12 descendants so the scan has plenty to parallelize.
+  const NODES = [{ id: "parent", title: "Parent", parentPageId: null, hasChildren: true }];
+  for (let i = 0; i < 12; i++) {
+    NODES.push({ id: `k${i}`, title: `Kid ${i}`, parentPageId: "parent", hasChildren: false });
+  }
+
+  let inFlight = 0;
+  let maxInFlight = 0;
+
+  const { baseURL } = await spawn(async (req, res) => {
+    const raw = await readBody(req);
+    if (handleLogin(req, res)) return;
+    if (req.url === "/api/pages/tree") {
+      sendJson(res, 200, { success: true, data: { items: NODES } });
+      return;
+    }
+    if (req.url === "/api/comments") {
+      const body = JSON.parse(raw || "{}");
+      inFlight++;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      // Hold the response briefly so concurrent fetches actually overlap.
+      setTimeout(() => {
+        inFlight--;
+        // Every page carries one fresh comment so ordering is observable.
+        sendJson(res, 200, {
+          success: true,
+          data: {
+            items: [
+              { id: `c-${body.pageId}`, createdAt: "2030-01-01T00:00:00.000Z", content: null },
+            ],
+            meta: { nextCursor: null },
+          },
+        });
+      }, 25);
+      return;
+    }
+    sendJson(res, 404, {});
+  });
+
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+  const result = await client.checkNewComments(
+    "space-1",
+    "2020-01-01T00:00:00.000Z",
+    "parent",
+  );
+
+  // 13 pages (parent + 12 kids) were scanned; each had a fresh comment.
+  assert.equal(result.checkedPages, 13, "all pages scanned");
+  assert.equal(result.totalNewComments, 13, "one fresh comment per page");
+  // Parallelism: more than one request was in flight at once, but never above the
+  // cap (6). A serial implementation would show maxInFlight === 1.
+  assert.ok(maxInFlight > 1, `expected concurrent fetches, saw max ${maxInFlight}`);
+  assert.ok(maxInFlight <= 6, `concurrency must be bounded, saw ${maxInFlight}`);
+  // Deterministic order: results follow the page-enumeration order (parent first).
+  assert.equal(result.comments[0].pageId, "parent", "results preserve page order");
+  assert.deepEqual(
+    result.comments.map((r) => r.pageId),
+    ["parent", ...Array.from({ length: 12 }, (_, i) => `k${i}`)],
+    "result order matches the enumeration order regardless of finish order",
+  );
+});
+
+// -----------------------------------------------------------------------------
+// 7) checkNewComments partial failure (#490): the concurrent scan is resilient —
+//    if ONE page's /comments fetch rejects (deleted mid-scan, a transient 500),
+//    that page is skipped and the WHOLE scan still resolves with every other
+//    page's fresh comments. A single failing fetch must never reject the batch
+//    (Promise.all in mapWithConcurrency would otherwise abort all of it) nor
+//    corrupt the deterministic order of the pages that DID succeed.
+// -----------------------------------------------------------------------------
+test("checkNewComments skips a page whose fetch fails and still reports the rest", async () => {
+  const NODES = [{ id: "parent", title: "Parent", parentPageId: null, hasChildren: true }];
+  for (let i = 0; i < 5; i++) {
+    NODES.push({ id: `k${i}`, title: `Kid ${i}`, parentPageId: "parent", hasChildren: false });
+  }
+  // The one page whose comment fetch blows up (500 -> listComments rejects).
+  const FAILING = "k2";
+
+  const { baseURL } = await spawn(async (req, res) => {
+    const raw = await readBody(req);
+    if (handleLogin(req, res)) return;
+    if (req.url === "/api/pages/tree") {
+      sendJson(res, 200, { success: true, data: { items: NODES } });
+      return;
+    }
+    if (req.url === "/api/comments") {
+      const body = JSON.parse(raw || "{}");
+      if (body.pageId === FAILING) {
+        // A transient server error on exactly one page's fetch.
+        sendJson(res, 500, { success: false, message: "boom" });
+        return;
+      }
+      sendJson(res, 200, {
+        success: true,
+        data: {
+          items: [
+            { id: `c-${body.pageId}`, createdAt: "2030-01-01T00:00:00.000Z", content: null },
+          ],
+          meta: { nextCursor: null },
+        },
+      });
+      return;
+    }
+    sendJson(res, 404, {});
+  });
+
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+  // Must RESOLVE (not reject) despite one page's fetch failing.
+  const result = await client.checkNewComments(
+    "space-1",
+    "2020-01-01T00:00:00.000Z",
+    "parent",
+  );
+
+  // Every page in scope was still scanned (the failing one counts as checked).
+  assert.equal(result.checkedPages, 6, "all pages scanned incl. the failing one");
+  // The failing page contributes nothing; the other 5 each report one comment.
+  assert.equal(result.pagesWithNewComments, 5, "the failing page is dropped");
+  assert.equal(result.totalNewComments, 5, "only the succeeding pages' comments");
+  const reportedIds = result.comments.map((r) => r.pageId);
+  assert.ok(!reportedIds.includes(FAILING), "the failing page is absent from results");
+  // Order of the survivors is still the deterministic enumeration order (the hole
+  // left by the failing page is closed without reordering the rest).
+  assert.deepEqual(
+    reportedIds,
+    ["parent", "k0", "k1", "k3", "k4"],
+    "survivors keep enumeration order with the failing page removed",
+  );
+});

packages/token-estimate/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@docmost/token-estimate",
+  "version": "0.1.0",
+  "description": "Shared, provider-agnostic token estimator (chars/2.5) used by the AI-chat client counter and the server history-replay budgeter, so the two never diverge.",
+  "private": true,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "4.1.6"
+  }
+}

packages/token-estimate/src/index.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { estimateTokens, CHARS_PER_TOKEN } from './index';
+
+describe('estimateTokens (shared chars/2.5)', () => {
+  it('returns 0 for empty / nullish input', () => {
+    expect(estimateTokens('')).toBe(0);
+    expect(estimateTokens(null)).toBe(0);
+    expect(estimateTokens(undefined)).toBe(0);
+  });
+
+  it('uses the chars/2.5 ratio, ceiled', () => {
+    expect(CHARS_PER_TOKEN).toBe(2.5);
+    // 5 chars / 2.5 = 2
+    expect(estimateTokens('abcde')).toBe(2);
+    // any non-empty string is at least 1 token (ceil)
+    expect(estimateTokens('a')).toBe(1);
+    // 100 chars / 2.5 = 40
+    expect(estimateTokens('x'.repeat(100))).toBe(40);
+  });
+
+  it('counts Cyrillic ~2x higher than the old chars/4 rule (no undercount)', () => {
+    const cyr = 'привет мир как дела'; // 19 chars
+    expect(estimateTokens(cyr)).toBe(Math.ceil(19 / 2.5)); // 8
+    expect(estimateTokens(cyr)).toBeGreaterThan(Math.ceil(19 / 4)); // > 5
+  });
+
+  it('is deterministic / byte-stable (same input => same output)', () => {
+    const s = 'the quick brown fox';
+    expect(estimateTokens(s)).toBe(estimateTokens(s));
+  });
+});

packages/token-estimate/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared, provider-agnostic token estimator (#490).
+ *
+ * No provider exposes an exact tokenizer we can afford to run on the hot path (a
+ * real BPE pass is O(n²)-ish, bloats the client bundle, and is wrong for
+ * Gemini/Ollama anyway), so both the client's in-body counter AND the server's
+ * history-replay budgeter use this ONE cheap chars-based heuristic. Keeping it in
+ * a single shared module is deliberate: two independent estimators drift, and then
+ * "the badge shows 60%" while "the budgeter already trimmed" — the exact confusion
+ * this package prevents.
+ *
+ * Ratio: **chars / 2.5**. Most content here is Cyrillic, where a token is ~2.5
+ * characters; the common English `chars/4` rule of thumb UNDER-counts Cyrillic by
+ * ~2×, which for a budget check is the dangerous direction (it lets the context
+ * overflow). 2.5 slightly over-estimates pure English/code, which is the SAFE
+ * direction for a budget. This is an estimate, never an exact count — the
+ * authoritative figure is always the provider's reported usage; the estimate is
+ * for UI affordances, the delta of not-yet-sent messages, and deciding what to
+ * trim.
+ */
+
+/** Characters per token for the shared estimate. See the module comment. */
+export const CHARS_PER_TOKEN = 2.5;
+
+/**
+ * Rough token estimate for a piece of text (chars / {@link CHARS_PER_TOKEN}).
+ * Returns 0 for empty/nullish input, and ceils so any non-empty text counts as at
+ * least one token. Pure and deterministic (byte-stable), so the same text always
+ * yields the same estimate — which the server budgeter relies on to keep replay
+ * trimming stable turn to turn (provider prompt-cache friendliness).
+ */
+export function estimateTokens(text: string | null | undefined): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}

packages/token-estimate/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts"]
+}

pnpm-lock.yaml

@@ -287,6 +287,9 @@ importers:
       '@docmost/prosemirror-markdown':
         specifier: workspace:*
         version: link:../../packages/prosemirror-markdown
+      '@docmost/token-estimate':
+        specifier: workspace:*
+        version: link:../../packages/token-estimate
       '@excalidraw/excalidraw':
         specifier: 0.18.0-3a5ef40
         version: 0.18.0-3a5ef40(@types/react-dom@18.3.1)(@types/react@18.3.12)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
@@ -561,6 +564,9 @@ importers:
       '@docmost/prosemirror-markdown':
         specifier: workspace:*
         version: link:../../packages/prosemirror-markdown
+      '@docmost/token-estimate':
+        specifier: workspace:*
+        version: link:../../packages/token-estimate
       '@fastify/compress':
         specifier: ^9.0.0
         version: 9.0.0
@@ -1148,6 +1154,15 @@ importers:
         specifier: 4.1.6
         version: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@20.19.43)(@vitest/coverage-v8@4.1.6)(happy-dom@20.8.9)(jsdom@25.0.0)(vite@8.0.5(@types/node@20.19.43)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
 
+  packages/token-estimate:
+    devDependencies:
+      typescript:
+        specifier: ^5.0.0
+        version: 5.9.3
+      vitest:
+        specifier: 4.1.6
+        version: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@25.5.0)(@vitest/coverage-v8@4.1.6)(happy-dom@20.8.9)(jsdom@27.4.0(@noble/hashes@2.0.1))(vite@8.0.5(@types/node@25.5.0)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
+
 packages:
 
   '@aashutoshrathi/word-wrap@1.2.6':