Merge pull request 'epic #497 волна 1 — интеграция четырёх approved-итераций (#486/#487/#488/#489) → develop' (#511) from integ/497-wave1 into develop

Reviewed-on: #511

.gitignore

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

apps/client/package.json

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

@@ -86,19 +86,11 @@ const MIN_HEIGHT = 400;
 // Margin kept between the window and the viewport edges while dragging.
 const EDGE_MARGIN = 8;
 
-// #184 phase 1.5 / #430: backstop for the degraded-poll fallback. The poll is
+// #184 phase 1.5 / #430 / #488: the degraded-poll fallback. The window owns only
-// armed when a resume attempt could not attach to the live run and disarmed by the
+// a DUMB 2.5s timer, gated by an armed flag; the THREAD's run-lifecycle FSM owns
-// thread on settle / local stream; this cap is the ONLY backstop against an endless
+// arm/disarm AND the inactivity cap that turns a stuck run into a `stalled` banner
-// tick (a stuck 'streaming' row before the boot-sweep, or a user-tail 204 with no
+// (#488 commit 4a — the cap moved into the thread so polling->stalled is a single
-// run).
+// FSM transition; the window no longer silently stops polling at the cap).
-//
-// #430: measured from RUN ACTIVITY, not from arm-time. A real autonomous run takes
-// 11-25 min — longer than a fixed 10-min-from-start cap, which used to cut the poll
-// off mid-run. Instead we cap on INACTIVITY: keep polling as long as the run is
-// still making progress (its persisted rows keep changing), and only give up after
-// this long with NO new activity. A genuinely stuck run produces no row changes, so
-// the idle cap still bounds it; a long-but-progressing run polls to completion.
-const DEGRADED_POLL_IDLE_MAX_MS = 10 * 60_000;
 
 /** Compact token formatter: 1.2M / 3.4k / 950. */
 function formatTokens(n: number): string {
@@ -259,17 +251,13 @@ export default function AiChatWindow() {
     [roles],
   );
 
-  // #184 phase 1.5: degraded-poll fallback (replaces the F4/F5/F7 latches). When
+  // #184 phase 1.5 / #488: degraded-poll fallback. ChatThread's FSM arms this via
-  // ChatThread could not attach to a still-running run it arms this via
+  // onResumeFallback(true) when it enters a poll-bearing recovery (attach 204 /
-  // onResumeFallback(true); the thread disarms it on settle / local stream. The
+  // starved finish / stop) and disarms it on settle / local stream / stalled. The
-  // window only OWNS the timer (armedAtRef stamps when it was armed for the cap).
+  // window owns ONLY the dumb 2.5s timer; the THREAD owns arm/disarm AND the
+  // inactivity cap (a stuck run -> the thread's `stalled` banner disarms this).
   const [degradedPoll, setDegradedPoll] = useState(false);
-  // #430: timestamp of the LAST run activity while the poll is armed — stamped on
-  // arm and re-stamped whenever the polled rows change (see the effect below). The
-  // idle cap is measured from this, so a long-but-progressing run keeps polling.
-  const lastActivityAtRef = useRef(0);
   const onResumeFallback = useCallback((active: boolean): void => {
-    if (active) lastActivityAtRef.current = Date.now();
     setDegradedPoll(active);
   }, []);
   // Reset the degraded poll whenever the open chat changes: it is scoped to the
@@ -281,33 +269,17 @@ export default function AiChatWindow() {
   const { data: messageRows, isLoading: messagesLoading } =
     useAiChatMessagesQuery(
       activeChatId ?? undefined,
-      // DELIBERATELY DUMB (invariant 8 / task 2.4): poll every 2.5s while armed
+      // DELIBERATELY DUMB: poll every 2.5s WHILE ARMED, otherwise off. NO error
-      // and while the run is still active (#430: under the INACTIVITY cap, not a
+      // checks (TanStack resets fetchFailureCount each fetch; the poll must survive
-      // fixed-from-start cap); otherwise off. NO error checks (TanStack v5 resets
+      // a server restart), NO tail checks, NO cap here — the settled/stalled/idle-cap
-      // fetchFailureCount each fetch, so consecutive errors are not expressible —
+      // semantics all live in ChatThread's FSM, which disarms via onResumeFallback.
-      // and the poll must survive a server restart) and NO tail checks (the
+      () => (degradedPoll === true ? 2500 : false),
-      // settled/local-stream semantics live in ChatThread, which disarms via
-      // onResumeFallback(false)). The idle cap is the only backstop.
-      () =>
-        degradedPoll === true &&
-        Date.now() - lastActivityAtRef.current < DEGRADED_POLL_IDLE_MAX_MS
-          ? 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.
       windowOpen,
     );
 
-  // #430: re-stamp the activity clock whenever the polled rows change while the
-  // poll is armed. TanStack keeps the same `messageRows` reference across refetches
-  // that return deep-equal data (structural sharing), so a new reference means the
-  // run genuinely progressed — which extends the inactivity cap above. A stuck run
-  // yields no reference change, so the cap eventually fires and stops the poll.
-  useEffect(() => {
-    if (degradedPoll) lastActivityAtRef.current = Date.now();
-  }, [degradedPoll, messageRows]);
-
   // #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/services/ai-chat-service.ts

@@ -57,6 +57,25 @@ export async function stopRun(
   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
+ * and to VERIFY after a supersede mismatch (an observer following a superseded
+ * run asks for the latest run and follows it). Returns the latest run row (with
+ * its `id` and `status`) and its projected assistant message, or `run: null` when
+ * the chat has never had a run. Owner-gated server-side.
+ */
+export async function getRun(chatId: string): Promise<{
+  run: { id: string; status: string } | null;
+  message: IAiChatMessageRow | null;
+}> {
+  const req = await api.post<{
+    run: { id: string; status: string } | null;
+    message: IAiChatMessageRow | null;
+  }>("/ai-chat/run", { chatId });
+  return req.data;
+}
+
 /**
  * Resolve the chat bound to a document (the current user's most-recent chat
  * created on that page), or null when there is none. Drives auto-open-on-page.

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

@@ -0,0 +1,183 @@
+# AI-chat run-lifecycle FSM — design spec (#488)
+
+This is the written design that `run-fsm.ts` implements. It ships in the PR (issue
+#488 commit 1: "the spec is written FIRST and enters the PR"). It has four parts:
+(1) the event × state transition table, (2) the map of every `chat-thread.tsx` ref
+to {FSM state | FSM context | stays data}, (3) the run-fact protocol, (4) the
+invariants.
+
+The reducer is a **pure function** `reduce(machine, event) → machine`. The returned
+machine carries the **command effects** for that transition; a thin runtime in
+`chat-thread.tsx` dispatches events and executes effects. Because it is pure, the
+whole machine is enumerable and unit-tested directly (event × state → next state is
+the observable property) — see `run-fsm.test.ts`.
+
+---
+
+## 1. Event × state transition table
+
+Phases: `idle | sending | streaming | attaching | reconnecting(attempt,failed) |
+polling(reason) | stalled | stopping | superseding | error(kind)`.
+Context (orthogonal): `epoch`, `ownership: local|observer`, `runFact: {runId}|null`,
+`liveFollow` (are we following a live run we locally streamed — the reconnect
+ladder — vs a one-shot mount-attach resume? both are `observer`, but a live-follow
+drop RE-ENTERS the ladder (#488 commit 3) while a mount-resume drop polls).
+
+Legend: **†** = command-transition (bumps `epoch`, I1). Effects in `[…]`.
+
+| Event (source) | From phase(s) | → To phase | Effects / ctx |
+|---|---|---|---|
+| `SEND_LOCAL` (user send) | idle, error, polling, stalled, reconnecting | sending **†** | `[cancelReconnect, disarmPoll]`, ownership=local |
+| `STREAM_START{runId}` (SDK `start` metadata) | sending, attaching, reconnecting, superseding | streaming | `[cancelReconnect, disarmPoll]`, runFact←runId |
+| `FINISH_CLEAN` (onFinish clean) | streaming, … | idle | `[disarmPoll, cancelReconnect]`, runFact←null |
+| `FINISH_ABORT` (onFinish isAbort) | streaming, stopping | idle | `[disarmPoll, cancelReconnect]`, runFact←null (I4 exits stopping by this DATA) |
+| `FINISH_DISCONNECT` (observer, NOT liveFollow) | streaming(observer) | polling(disconnect-visible) | `[armPoll]` (a mount-resume drop polls) |
+| `FINISH_DISCONNECT{hasVisibleContent}` (local drop OR liveFollow) | streaming | reconnecting(1) **†** *iff runFact\|liveFollow* | `[scheduleReconnect(1)]` (+`armPoll` if visible), ownership=observer, liveFollow=true (commit 3: repeatable) |
+| `FINISH_DISCONNECT` (no runFact, not liveFollow) | streaming | idle | runFact←null (plain terminal "connection lost") |
+| `STREAM_INCOMPLETE{reason}` (observer starved/torn clean finish) | streaming(observer) | polling(reason) | `[armPoll(reason)]` |
+| `FINISH_ERROR{kind}` (onFinish isError) | any | error(kind) | `[disarmPoll, cancelReconnect]`, runFact←null |
+| `STREAM_START{runId}` (first assistant frame of a local turn) | sending | streaming | runFact←runId, `[cancelReconnect, disarmPoll]` |
+| `ATTACH_START{runId}` (mount resume) | **idle only** (F2) | attaching **†** | `[resumeStream]`, ownership=observer, runFact←runId; ignored from any non-idle phase |
+| `ATTACH_LIVE` (attach GET 2xx) | attaching | streaming | — |
+| `ATTACH_NONE` (attach GET 204/err/throw) | attaching | polling(attach-none) | `[armPoll(attach-none)]` |
+| `RECONNECT_ATTEMPT{n}` (backoff timer) | reconnecting | reconnecting(n) **†** | `[resumeStream]` |
+| `RECONNECT_ATTACHED` (reconnect GET 2xx) | reconnecting | streaming | `[cancelReconnect, disarmPoll]` — **counter reset** (commit 3) |
+| `RECONNECT_NONE` (reconnect GET 204/err), attempt<MAX | reconnecting | reconnecting(n+1) **†** | `[armPoll(attach-none), scheduleReconnect(n+1)]` |
+| `RECONNECT_NONE`, attempt=MAX | reconnecting | reconnecting(MAX, failed) | `[armPoll(reconnect-exhausted)]` |
+| `RETRY` (manual, failed banner) | reconnecting(failed) | reconnecting(1) **†** | `[resumeStream]` |
+| `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) |
+| `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) |
+| `SUPERSEDE_REQUESTED{targetRunId}` (interrupt+send) | streaming, reconnecting, polling, error | superseding **†** | `[supersede(target), cancelReconnect, disarmPoll]` |
+| `SUPERSEDE_READY{runId}` (CAS ok) | superseding | streaming | ownership=local, runFact←runId |
+| `SUPERSEDE_MISMATCH{currentRunId}` (409 SUPERSEDE_TARGET_MISMATCH) | superseding | error(supersede-mismatch) | `[postRun(verify)]`, runFact←currentRunId |
+| `SUPERSEDE_TIMEOUT` (409 SUPERSEDE_TIMEOUT) | superseding | error(supersede-timeout) | — (composer keeps text; no auto-retry) |
+| `SUPERSEDE_INVALID` (409 SUPERSEDE_INVALID) | superseding | error(supersede-invalid) | — |
+| `RUN_ALREADY_ACTIVE{activeRunId}` (409 A_RUN_ALREADY_ACTIVE, plain POST) | sending | error(run-already-active) | runFact←activeRunId (composer offers supersede; NO auto-retry) |
+| `DISPOSE` (unmount) | any | idle **†** | `[abortAttach, cancelReconnect, disarmPoll]` (I1/I5 — epoch++ kills late callbacks) |
+
+**`stopping` honors any finish (re-review MEDIUM):** BEFORE the epoch filter, a
+stream finish (`FINISH_*`/`STREAM_INCOMPLETE`) arriving in phase `stopping` exits
+`stopping -> idle` regardless of generation. A plain Stop has no successor stream,
+so the aborted stream's finish IS the expected end (I4 exit by data) — and it
+carries the PRE-stop generation (STOP_REQUESTED bumped the epoch), so the filter
+would otherwise strand the machine in `stopping` (no idle-cap covers it). The filter
+stays in force for `superseding` (that is the F1 supersede drop).
+
+**Epoch filter (I1):** the reducer then drops any event carrying an `epoch` that
+does not equal the current `ctx.epoch`. Outcome events (`STREAM_START`, `ATTACH_*`,
+`RECONNECT_*`, `SUPERSEDE_*`, **`FINISH_*`/`STREAM_INCOMPLETE`**, `RUN_FACT`) are
+stamped with the generation the corresponding STREAM started under (the runtime
+holds a per-owned-stream `turnEpoch`); trigger events (user actions, fresh
+disconnects) carry no epoch. **F1:** this is what makes a SUPERSEDED stream's late
+`onFinish` (a dead stream A closing after the CAS started stream B) get dropped, so
+A cannot drive the live new run into a false reconnect or reset its run-fact. The
+supersede path additionally ABORTS A and starts B only from A's onFinish (a
+microtask), because ai@6 `AbstractChat.makeRequest` corrupts overlapping streams
+(A's `finally` reads then nulls the shared `activeResponse`).
+
+**Removed events (scope-cut, internal review):** `RUN_SUPERSEDED` (a ghost feature —
+never dispatched; the observer-superseded case is handled by the degraded poll,
+which follows the latest rows regardless of runId), `RECONNECT_BEGIN` (reconnect is
+entered by `FINISH_DISCONNECT`), and `POLL_ACTIVITY` (the window's activity clock was
+removed when the idle-cap moved into the thread). The reducer and this table now
+share exactly the dispatched event set.
+
+### 409-code → event map (the real #487 contract consumed here)
+
+| Server response | Event dispatched | error kind → banner |
+|---|---|---|
+| 409 `A_RUN_ALREADY_ACTIVE` (+ body.activeRunId) | `RUN_ALREADY_ACTIVE{activeRunId}` | run-already-active → "already answering / interrupt & send" |
+| 409 `SUPERSEDE_TARGET_MISMATCH` (+ body.activeRunId) | `SUPERSEDE_MISMATCH{currentRunId}` | supersede-mismatch → verify via /run |
+| 409 `SUPERSEDE_TIMEOUT` | `SUPERSEDE_TIMEOUT` | supersede-timeout → "couldn't interrupt in time, resend" |
+| 409 `SUPERSEDE_INVALID` | `SUPERSEDE_INVALID` | supersede-invalid → "couldn't interrupt this run" |
+| 503 `A_RUN_BEGIN_FAILED` | `FINISH_ERROR{begin-failed}` | begin-failed → "could not start, temporary" |
+
+---
+
+## 2. Ref-map — every `chat-thread.tsx` ref → its new home  (MIGRATION RESOLVED)
+
+The migration is COMPLETE: the 13 run-lifecycle FLAGS below are GONE from
+`chat-thread.tsx` (collapsed into FSM phase/ctx/effects, or deleted). What remains
+are identity/data mirrors, effect-owned controllers/timers, and ONE React-liveness
+bit — none of which is a run-lifecycle flag, so the post-merge "no new flags" rule
+holds. **Pending column: empty.**
+
+| # | Old ref | Resolved to | Where now |
+|---|---|---|---|
+| 1 | `reconcileTailRef` | **FSM phase** | reconcile-merge gated on `phase ∈ {polling, reconnecting, stopping}` |
+| 2 | `noStreamHandledRef` | **FSM epoch (I1)** | the attach outcome's epoch guard drops the stale/second outcome |
+| 3 | `onNoActiveStreamRef` | **FSM event** | transport → `handleAttachOutcome` dispatches `ATTACH_NONE`/`RECONNECT_NONE` |
+| 4 | `onReconnectAttachedRef` | **FSM event** | transport dispatches `ATTACH_LIVE` / `RECONNECT_ATTACHED` |
+| 5 | `resumedTurnRef` + `resumedTurn` state | **FSM ctx `ownership`** | `ownership==='observer'` ⇒ never flush; hides "Send now" |
+| 6 | `reconnectStateRef` + `reconnectState` state | **FSM phase** | `reconnecting(attempt,failed)` renders the banner |
+| 7 | `reconnectTimerRef` | **effect-owned timer** | owned by `scheduleReconnect`/`cancelReconnect` effects (not a flag) |
+| 8 | `flushOnAbortRef` | **DELETED** | the stop→flush dance is replaced by the CAS supersede (commit 5) |
+| 9 | `interruptNextSendRef` | **DELETED** | the server injects the interrupt note from the supersede itself |
+| 10 | `supersedeRetryRef` | **DELETED** (commit 5) | the client 409 retry ladder is gone; CAS supersede replaces it |
+| 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 |
+| 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 |
+| NEW | `idleCapTimerRef` | **effect-owned timer** | the stalled inactivity cap → `POLL_IDLE_CAP` (commit 4a); not a flag |
+
+Net: the 13 lifecycle flags (#1–#13) are eliminated: **8** → FSM phase/ctx/epoch/event
+(#1–#6, #11, #13), **3** deleted (#8/#9/#10), **`reconnectTimerRef` (#7)** becomes an
+effect-owned controller, and **`mountedRef` (#12)** is retained as React liveness
+(8 + 3 + 1 + 1 = 13). (`attachAbortRef` (#16) is outside the #1–#13 set — it was
+already an effect-owned controller.) Two effect-owned timers + one send-plumbing data
+ref are added — none is a boolean lifecycle latch.
+
+---
+
+## 3. Run-fact protocol (`runFact: {runId} | null`) — I3
+
+"A run is active" is first-class from the SERVER, not inferred from an assistant
+message. Sources, in the order they update `ctx.runFact`:
+
+1. **Init (mount):** `POST /ai-chat/run { chatId }` → `{ run, message }`. A `run`
+   with a non-terminal `status` seeds `runFact = { runId: run.id }`; a null/terminal
+   run seeds `null`. This is what arms the resume attempt (`ATTACH_START`) — the
+   attempt is armed ONLY on a positive fact (commit 4b: a user-tail with no active
+   run no longer arms a pointless poll on every open).
+2. **Live update:** the `start` stream metadata carries `runId` → `STREAM_START{runId}`.
+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`.
+
+Pessimism rule: a stale-but-positive fact PERMITS entering recovery (attach); the
+204 then cuts it. A fresh negative fact gates recovery OUT immediately.
+
+---
+
+## 4. Invariants
+
+- **I1 — Epoch (generation counter).** Every command-emitting transition bumps
+  `ctx.epoch`; every async outcome event carries its issuing epoch; the reducer
+  drops stale-epoch outcomes. Replaces the one-shot-ref zoo (`noStreamHandledRef`,
+  the flush/interrupt/supersede one-shots, the `mountedRef` late-callback gate).
+- **I2 — Ownership is context, not state.** `local | observer` is orthogonal to the
+  transport phase. The queue flushes ONLY under local ownership; an observer
+  following a detached run never flushes (was `resumedTurnRef`).
+- **I3 — Run-fact is first-class from the server.** Reconnect is entered by the
+  run-fact, not by an assistant message (commit 2). A fresh negative fact cancels
+  recovery.
+- **I4 — Exit `stopping` by DATA.** A terminal row / negative run-fact / terminal
+  finish exits `stopping`, never the stopRun HTTP response (which returns after the
+  abort but before finalization — keying off it would unlock the composer on a 409).
+- **I5 — Dispose protocol.** Command controllers (attach GET, POST /stream, POST
+  /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.
+- **Queue** stays a data structure; flush/interrupt decisions are transitions.

apps/client/src/features/ai-chat/state/run-fsm.test.ts

@@ -0,0 +1,482 @@
+import { describe, it, expect } from "vitest";
+import {
+  reduce,
+  initialMachine,
+  reconnectDelayMs,
+  RECONNECT_MAX_ATTEMPTS,
+  type Machine,
+  type Effect,
+  type Event,
+} from "./run-fsm";
+
+// Drive a sequence of events through the reducer, returning the final machine.
+function run(m: Machine, ...events: Event[]): Machine {
+  return events.reduce(reduce, m);
+}
+function withRunFact(runId = "run-1"): Machine {
+  return {
+    ...initialMachine(),
+    ctx: { epoch: 0, ownership: "local", runFact: { runId }, liveFollow: false },
+  };
+}
+function effectTypes(m: Machine): string[] {
+  return m.effects.map((e) => e.type);
+}
+function hasEffect(m: Machine, type: Effect["type"]): boolean {
+  return m.effects.some((e) => e.type === type);
+}
+
+describe("run-fsm — epoch invariant (I1)", () => {
+  it("drops an outcome carrying a stale epoch", () => {
+    // A command bumps the epoch; an outcome stamped with the OLD epoch is dropped.
+    const m0 = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" }); // epoch 0->1, attaching
+    expect(m0.ctx.epoch).toBe(1);
+    expect(m0.phase.name).toBe("attaching");
+    // A late ATTACH_LIVE from a SUPERSEDED attempt (epoch 0) must NOT drive us.
+    const stale = reduce(m0, { type: "ATTACH_LIVE", epoch: 0 });
+    expect(stale.phase.name).toBe("attaching");
+    expect(stale.effects).toEqual([]);
+  });
+
+  it("applies an outcome carrying the current epoch", () => {
+    const m0 = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    const live = reduce(m0, { type: "ATTACH_LIVE", epoch: m0.ctx.epoch });
+    expect(live.phase.name).toBe("streaming");
+  });
+
+  it("an outcome with no epoch is never dropped (trigger events)", () => {
+    const m0 = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    const disposed = reduce(m0, { type: "DISPOSE" });
+    expect(disposed.phase.name).toBe("idle");
+    expect(hasEffect(disposed, "abortAttach")).toBe(true);
+  });
+
+  it("every command-transition increments the epoch exactly once", () => {
+    let m = initialMachine();
+    const before = m.ctx.epoch;
+    m = reduce(m, { type: "SEND_LOCAL" });
+    expect(m.ctx.epoch).toBe(before + 1);
+    m = reduce(m, { type: "STOP_REQUESTED" });
+    expect(m.ctx.epoch).toBe(before + 2);
+  });
+});
+
+describe("run-fsm — local turn", () => {
+  it("SEND_LOCAL → sending, local ownership, cancels recovery", () => {
+    const m = reduce(withRunFact(), { type: "SEND_LOCAL" });
+    expect(m.phase.name).toBe("sending");
+    expect(m.ctx.ownership).toBe("local");
+    expect(effectTypes(m)).toEqual(
+      expect.arrayContaining(["cancelReconnect", "disarmPoll"]),
+    );
+  });
+
+  it("STREAM_START adopts the runId into the run-fact and goes streaming", () => {
+    const m = run(initialMachine(), { type: "SEND_LOCAL" });
+    const s = reduce(m, { type: "STREAM_START", runId: "run-9", epoch: m.ctx.epoch });
+    expect(s.phase.name).toBe("streaming");
+    expect(s.ctx.runFact).toEqual({ runId: "run-9" });
+  });
+
+  it("FINISH_CLEAN → idle, run-fact cleared, poll/reconnect disarmed", () => {
+    const streaming = run(initialMachine(), { type: "SEND_LOCAL" }, { type: "STREAM_START", runId: "r" });
+    const done = reduce(streaming, { type: "FINISH_CLEAN" });
+    expect(done.phase.name).toBe("idle");
+    expect(done.ctx.runFact).toBeNull();
+  });
+});
+
+// #488 commit 2 — SSE break BEFORE the first assistant frame must still recover.
+describe("run-fsm — commit 2: reconnect by run-fact, not by assistant message", () => {
+  it("FINISH_DISCONNECT with an active run-fact → reconnecting (even with no visible content)", () => {
+    // Setup-phase break: no assistant frame yet, but a run-fact exists.
+    const streaming = withRunFact("run-2");
+    const m = reduce(streaming, {
+      type: "FINISH_DISCONNECT",
+      hasVisibleContent: false,
+      epoch: streaming.ctx.epoch,
+    });
+    expect(m.phase.name).toBe("reconnecting");
+    if (m.phase.name === "reconnecting") expect(m.phase.attempt).toBe(1);
+    expect(m.ctx.ownership).toBe("observer");
+    expect(hasEffect(m, "scheduleReconnect")).toBe(true);
+    // No visible content -> no poll arm yet (the reconnect ladder rebuilds it).
+    expect(hasEffect(m, "armPoll")).toBe(false);
+  });
+
+  it("FINISH_DISCONNECT WITH visible content also arms the poll", () => {
+    const m = reduce(withRunFact("run-2"), {
+      type: "FINISH_DISCONNECT",
+      hasVisibleContent: true,
+      epoch: 0,
+    });
+    expect(m.phase.name).toBe("reconnecting");
+    expect(hasEffect(m, "armPoll")).toBe(true);
+  });
+
+  it("FINISH_DISCONNECT with NO run-fact → idle (plain connection-lost)", () => {
+    const m = reduce(initialMachine(), {
+      type: "FINISH_DISCONNECT",
+      hasVisibleContent: true,
+      epoch: 0,
+    });
+    expect(m.phase.name).toBe("idle");
+  });
+});
+
+// #488 commit 3 — a SECOND break after a successful re-attach starts a NEW ladder.
+describe("run-fsm — commit 3: repeated reconnect cycles", () => {
+  it("two breaks in a row produce two reconnect cycles (counter resets on attach)", () => {
+    let m = withRunFact("run-3");
+    // First break -> reconnecting(1).
+    m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("reconnecting");
+    // Attempt fires, re-attaches live.
+    m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: 1, epoch: m.ctx.epoch });
+    m = reduce(m, { type: "RECONNECT_ATTACHED", epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("streaming");
+    // SECOND break: the counter was reset, so a fresh ladder starts at attempt 1
+    // (the old one-shot !wasResumed gate would have sent this to silent poll).
+    m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("reconnecting");
+    if (m.phase.name === "reconnecting") expect(m.phase.attempt).toBe(1);
+    expect(hasEffect(m, "scheduleReconnect")).toBe(true);
+  });
+
+  it("a MOUNT-attach observer drop falls to POLL, not the reconnect ladder", () => {
+    // Distinguishes commit 3 from a one-shot resume: an observer that never
+    // live-followed (liveFollow false) polls on a drop.
+    let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
+    expect(m.ctx.ownership).toBe("observer");
+    expect(m.ctx.liveFollow).toBe(false);
+    m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: true, epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("polling");
+    expect(hasEffect(m, "armPoll")).toBe(true);
+  });
+
+  it("STREAM_INCOMPLETE (observer starved/torn finish) → polling", () => {
+    let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
+    m = reduce(m, { type: "STREAM_INCOMPLETE", reason: "starved", epoch: m.ctx.epoch });
+    expect(m.phase).toEqual({ name: "polling", reason: "starved" });
+    expect(hasEffect(m, "armPoll")).toBe(true);
+  });
+
+  it("liveFollow is set on the first local drop and kept across a re-attach", () => {
+    let m = withRunFact("run-3");
+    m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
+    expect(m.ctx.liveFollow).toBe(true);
+    m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: 1, epoch: m.ctx.epoch });
+    m = reduce(m, { type: "RECONNECT_ATTACHED", epoch: m.ctx.epoch });
+    expect(m.ctx.liveFollow).toBe(true); // kept — so a second drop reconnects
+    // A clean finish clears it.
+    m = reduce(m, { type: "FINISH_CLEAN", epoch: m.ctx.epoch });
+    expect(m.ctx.liveFollow).toBe(false);
+  });
+
+  it("RECONNECT_NONE backs off through the ladder, then fails at the cap", () => {
+    let m = withRunFact("run-3");
+    m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: false, epoch: m.ctx.epoch });
+    for (let n = 1; n < RECONNECT_MAX_ATTEMPTS; n++) {
+      m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: n, epoch: m.ctx.epoch });
+      m = reduce(m, { type: "RECONNECT_NONE", epoch: m.ctx.epoch });
+      expect(m.phase.name).toBe("reconnecting");
+      if (m.phase.name === "reconnecting") {
+        expect(m.phase.attempt).toBe(n + 1);
+        expect(m.phase.failed).toBe(false);
+      }
+      // The belt-and-suspenders poll is armed each failed attempt.
+      expect(hasEffect(m, "armPoll")).toBe(true);
+    }
+    // Final attempt fails -> failed banner (Retry), poll armed.
+    m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: RECONNECT_MAX_ATTEMPTS, epoch: m.ctx.epoch });
+    m = reduce(m, { type: "RECONNECT_NONE", epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("reconnecting");
+    if (m.phase.name === "reconnecting") expect(m.phase.failed).toBe(true);
+    // RETRY restarts at attempt 1.
+    m = reduce(m, { type: "RETRY" });
+    expect(m.phase.name).toBe("reconnecting");
+    if (m.phase.name === "reconnecting") {
+      expect(m.phase.attempt).toBe(1);
+      expect(m.phase.failed).toBe(false);
+    }
+    expect(hasEffect(m, "resumeStream")).toBe(true);
+  });
+
+  it("reconnectDelayMs is the exponential backoff 1s,2s,4s,8s,16s", () => {
+    expect([1, 2, 3, 4, 5].map(reconnectDelayMs)).toEqual([1000, 2000, 4000, 8000, 16000]);
+  });
+});
+
+// #488 commit 4 — polling stalled-state + user-tail gating.
+describe("run-fsm — commit 4: stalled + run-fact gating", () => {
+  it("POLL_IDLE_CAP: polling → stalled with a banner (poll disarmed), not silent", () => {
+    let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("polling");
+    m = reduce(m, { type: "POLL_IDLE_CAP" });
+    expect(m.phase.name).toBe("stalled");
+    expect(hasEffect(m, "disarmPoll")).toBe(true);
+  });
+
+  it("RETRY from stalled re-arms the poll", () => {
+    let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
+    m = reduce(m, { type: "POLL_IDLE_CAP" });
+    m = reduce(m, { type: "RETRY" });
+    expect(m.phase.name).toBe("polling");
+    expect(hasEffect(m, "armPoll")).toBe(true);
+  });
+
+  it("a fresh NEGATIVE run-fact while attaching cancels recovery (user-tail, no active run)", () => {
+    // The mount POST /run returns no active run: attaching → idle, no poll armed.
+    let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "RUN_FACT", runFact: null, epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("idle");
+    expect(m.ctx.runFact).toBeNull();
+    expect(hasEffect(m, "disarmPoll")).toBe(true);
+  });
+
+  it("a negative run-fact while polling stops the poll", () => {
+    let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
+    m = reduce(m, { type: "RUN_FACT", runFact: null, epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("idle");
+  });
+
+  it("POLL_TERMINAL settles polling → idle (I4 data-driven exit)", () => {
+    let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "ATTACH_NONE", epoch: m.ctx.epoch });
+    m = reduce(m, { type: "POLL_TERMINAL" });
+    expect(m.phase.name).toBe("idle");
+    expect(m.ctx.runFact).toBeNull();
+  });
+});
+
+// #488 commit 5 — error classification + supersede CAS transitions.
+describe("run-fsm — commit 5: supersede CAS + error classification", () => {
+  it("SUPERSEDE_REQUESTED → superseding, fires the CAS effect, bumps epoch", () => {
+    const streaming = withRunFact("run-old");
+    const m = reduce(streaming, { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
+    expect(m.phase.name).toBe("superseding");
+    expect(m.ctx.epoch).toBe(streaming.ctx.epoch + 1);
+    const sup = m.effects.find((e) => e.type === "supersede");
+    expect(sup).toEqual({ type: "supersede", targetRunId: "run-old" });
+  });
+
+  it("SUPERSEDE_READY → streaming as the new local owner", () => {
+    let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
+    m = reduce(m, { type: "SUPERSEDE_READY", runId: "run-new", epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("streaming");
+    expect(m.ctx.ownership).toBe("local");
+    expect(m.ctx.runFact).toEqual({ runId: "run-new" });
+  });
+
+  it("SUPERSEDE_MISMATCH → error(supersede-mismatch) + verify via /run (no blind banner)", () => {
+    let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
+    m = reduce(m, { type: "SUPERSEDE_MISMATCH", currentRunId: "run-x", epoch: m.ctx.epoch });
+    expect(m.phase).toEqual({ name: "error", kind: "supersede-mismatch" });
+    expect(hasEffect(m, "postRun")).toBe(true);
+    expect(m.ctx.runFact).toEqual({ runId: "run-x" });
+  });
+
+  it("SUPERSEDE_TIMEOUT → error(supersede-timeout), no auto-retry effect", () => {
+    let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
+    m = reduce(m, { type: "SUPERSEDE_TIMEOUT", epoch: m.ctx.epoch });
+    expect(m.phase).toEqual({ name: "error", kind: "supersede-timeout" });
+    expect(m.effects).toEqual([]);
+  });
+
+  it("SUPERSEDE_INVALID → error(supersede-invalid)", () => {
+    let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
+    m = reduce(m, { type: "SUPERSEDE_INVALID", epoch: m.ctx.epoch });
+    expect(m.phase).toEqual({ name: "error", kind: "supersede-invalid" });
+  });
+
+  it("a stale SUPERSEDE outcome from a superseded epoch is dropped", () => {
+    let m = reduce(withRunFact("run-old"), { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
+    const supersedingEpoch = m.ctx.epoch;
+    // The user retriggers, bumping the epoch again.
+    m = reduce(m, { type: "SUPERSEDE_REQUESTED", targetRunId: "run-old" });
+    // The first CAS's late TIMEOUT (old epoch) must NOT knock us out of superseding.
+    const late = reduce(m, { type: "SUPERSEDE_TIMEOUT", epoch: supersedingEpoch });
+    expect(late.phase.name).toBe("superseding");
+  });
+
+  it("RUN_ALREADY_ACTIVE (plain POST gate) → error(run-already-active), no retry effect", () => {
+    const m = reduce(run(initialMachine(), { type: "SEND_LOCAL" }), { type: "RUN_ALREADY_ACTIVE" });
+    expect(m.phase).toEqual({ name: "error", kind: "run-already-active" });
+    expect(m.effects).toEqual([]);
+  });
+
+  it("#497/S4: RUN_ALREADY_ACTIVE{activeRunId} ADOPTS the server's active run as the run-fact", () => {
+    // The server sends `activeRunId` so a later supersede can TARGET that run
+    // instead of a blind promote+abort. Absorb it into runFact.
+    const m = reduce(run(initialMachine(), { type: "SEND_LOCAL" }), {
+      type: "RUN_ALREADY_ACTIVE",
+      activeRunId: "run-foreign",
+    });
+    expect(m.phase).toEqual({ name: "error", kind: "run-already-active" });
+    expect(m.ctx.runFact).toEqual({ runId: "run-foreign" });
+    expect(m.effects).toEqual([]);
+  });
+
+  it("#497/S4: RUN_ALREADY_ACTIVE without an activeRunId keeps the prior run-fact", () => {
+    const seeded = reduce(run(initialMachine(), { type: "SEND_LOCAL" }), {
+      type: "RUN_FACT",
+      runFact: { runId: "run-prior" },
+    });
+    const m = reduce(seeded, { type: "RUN_ALREADY_ACTIVE" });
+    expect(m.ctx.runFact).toEqual({ runId: "run-prior" });
+  });
+});
+
+// #488 F2 — a late mount `getRun → ATTACH_START` must not hijack a local turn.
+describe("run-fsm — F2: ATTACH_START only from idle", () => {
+  it("ATTACH_START from a local `sending` turn is ignored (no observer hijack)", () => {
+    const sending = reduce(initialMachine(), { type: "SEND_LOCAL" }); // idle -> sending, local
+    const m = reduce(sending, { type: "ATTACH_START", runId: "r" });
+    expect(m.phase.name).toBe("sending");
+    expect(m.ctx.ownership).toBe("local"); // NOT flipped to observer
+    expect(m.effects).toEqual([]); // no resumeStream
+  });
+
+  it("ATTACH_START from idle attaches as normal", () => {
+    const m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    expect(m.phase.name).toBe("attaching");
+    expect(m.ctx.ownership).toBe("observer");
+    expect(hasEffect(m, "resumeStream")).toBe(true);
+  });
+});
+
+describe("run-fsm — stop (I4: exit by data)", () => {
+  it("STOP_REQUESTED → stopping, fires stopRun + abortAttach, no data-independent exit", () => {
+    const m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
+    expect(m.phase.name).toBe("stopping");
+    expect(effectTypes(m)).toEqual(expect.arrayContaining(["stopRun", "abortAttach"]));
+  });
+
+  it("stopping exits on the aborted stream's finish carrying the PRE-STOP epoch", () => {
+    // MEDIUM (#488 re-review): STOP_REQUESTED is a command that BUMPS the epoch, but
+    // the runtime stamps the aborted stream's onFinish with the stream's START (pre-
+    // stop) generation — exactly what the component sends. `stopping` must HONOR
+    // that finish regardless of generation (no idle-cap covers `stopping`).
+    // MUTATION-VERIFY: remove the honor-in-`stopping` branch and this hangs in
+    // `stopping` (the epoch filter drops the pre-stop finish) -> red.
+    const preStopEpoch = withRunFact().ctx.epoch; // E1 (the stream's start epoch)
+    let m = reduce(withRunFact(), { type: "STOP_REQUESTED" }); // E1 -> E2, stopping
+    expect(m.ctx.epoch).toBe(preStopEpoch + 1);
+    m = reduce(m, { type: "FINISH_ABORT", epoch: preStopEpoch }); // NOT the current epoch
+    expect(m.phase.name).toBe("idle");
+    expect(m.ctx.runFact).toBeNull();
+  });
+
+  it("stopping exits on a clean finish carrying the pre-stop epoch too", () => {
+    const preStopEpoch = withRunFact().ctx.epoch;
+    let m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
+    m = reduce(m, { type: "FINISH_CLEAN", epoch: preStopEpoch });
+    expect(m.phase.name).toBe("idle");
+  });
+
+  it("stopping exits on a negative run-fact (data)", () => {
+    let m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
+    m = reduce(m, { type: "RUN_FACT", runFact: null, epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("idle");
+  });
+
+  // Review #4: `stopping` arms the poll but had no inactivity backstop.
+  it("review-4: POLL_IDLE_CAP in `stopping` exits to idle (bounded), NOT stalled", () => {
+    let m = reduce(withRunFact(), { type: "STOP_REQUESTED" });
+    expect(m.phase.name).toBe("stopping");
+    expect(hasEffect(m, "armPoll")).toBe(true);
+    // MUTATION-VERIFY: drop the `stopping` branch in POLL_IDLE_CAP and this hangs
+    // in `stopping` (poll forever) -> red.
+    m = reduce(m, { type: "POLL_IDLE_CAP" });
+    expect(m.phase.name).toBe("idle");
+    expect(hasEffect(m, "disarmPoll")).toBe(true);
+    expect(m.ctx.ownership).toBe("local");
+  });
+});
+
+// Review #1: positive attach outcomes must be guarded by the SOURCE phase — the
+// epoch filter alone is insufficient because POLL_TERMINAL uses to() (no epoch
+// bump) and does not abort the in-flight GET.
+describe("run-fsm — review-1: attach outcomes guarded by source phase", () => {
+  it("a late RECONNECT_ATTACHED after POLL_TERMINAL stays idle (no phantom streaming)", () => {
+    let m = withRunFact("run-1");
+    m = reduce(m, { type: "FINISH_DISCONNECT", hasVisibleContent: true, epoch: m.ctx.epoch });
+    m = reduce(m, { type: "RECONNECT_ATTEMPT", attempt: 1, epoch: m.ctx.epoch }); // attach GET
+    const epoch = m.ctx.epoch;
+    // The armed degraded poll reaches the terminal row FIRST (epoch unchanged).
+    m = reduce(m, { type: "POLL_TERMINAL" });
+    expect(m.phase.name).toBe("idle");
+    expect(m.ctx.epoch).toBe(epoch); // POLL_TERMINAL did NOT bump the epoch
+    // The slow GET returns live 2xx under the SAME epoch — must NOT resurrect.
+    m = reduce(m, { type: "RECONNECT_ATTACHED", epoch });
+    expect(m.phase.name).toBe("idle");
+  });
+
+  it("a late ATTACH_LIVE / ATTACH_NONE after leaving `attaching` is ignored", () => {
+    let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    const epoch = m.ctx.epoch;
+    m = reduce(m, { type: "ATTACH_NONE", epoch }); // attaching -> polling
+    m = reduce(m, { type: "POLL_TERMINAL" }); // -> idle (epoch unchanged)
+    expect(m.phase.name).toBe("idle");
+    m = reduce(m, { type: "ATTACH_LIVE", epoch }); // late 2xx, same epoch
+    expect(m.phase.name).toBe("idle");
+    // And a late ATTACH_NONE (not `attaching`) is a no-op too.
+    m = reduce(m, { type: "ATTACH_NONE", epoch });
+    expect(m.phase.name).toBe("idle");
+  });
+});
+
+// Review #2: every terminal transition resets ownership to local.
+describe("run-fsm — review-2: terminal transitions reset ownership to local", () => {
+  const observer = (): Machine => {
+    let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
+    expect(m.ctx.ownership).toBe("observer");
+    return m;
+  };
+  it("FINISH_CLEAN resets ownership", () => {
+    const m = reduce(observer(), { type: "FINISH_CLEAN", epoch: observer().ctx.epoch });
+    expect(m.ctx.ownership).toBe("local");
+  });
+  it("FINISH_ERROR / POLL_TERMINAL / RUN_FACT(null) reset ownership", () => {
+    let o = observer();
+    expect(reduce(o, { type: "FINISH_ERROR", kind: "stream", epoch: o.ctx.epoch }).ctx.ownership).toBe("local");
+    // POLL_TERMINAL from an observer polling phase
+    let p = reduce(observer(), { type: "STREAM_INCOMPLETE", reason: "starved", epoch: observer().ctx.epoch });
+    expect(reduce(p, { type: "POLL_TERMINAL" }).ctx.ownership).toBe("local");
+    // RUN_FACT(null) from an observer attaching phase
+    let a = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    expect(reduce(a, { type: "RUN_FACT", runFact: null, epoch: a.ctx.epoch }).ctx.ownership).toBe("local");
+  });
+});
+
+describe("run-fsm — ownership (I2) is context, orthogonal to phase", () => {
+  it("attach/reconnect set observer; send/supersede-ready set local", () => {
+    let m = reduce(initialMachine(), { type: "ATTACH_START", runId: "r" });
+    expect(m.ctx.ownership).toBe("observer");
+    m = reduce(m, { type: "ATTACH_LIVE", epoch: m.ctx.epoch });
+    expect(m.phase.name).toBe("streaming");
+    expect(m.ctx.ownership).toBe("observer"); // still observing a detached run
+    // A local send flips ownership back to local.
+    m = reduce(m, { type: "SEND_LOCAL" });
+    expect(m.ctx.ownership).toBe("local");
+  });
+});
+
+describe("run-fsm — dispose (I5)", () => {
+  it("DISPOSE from any phase aborts controllers and bumps epoch", () => {
+    let m = reduce(withRunFact(), { type: "ATTACH_START", runId: "r" });
+    const before = m.ctx.epoch;
+    m = reduce(m, { type: "DISPOSE" });
+    expect(m.phase.name).toBe("idle");
+    expect(m.ctx.epoch).toBe(before + 1);
+    expect(effectTypes(m)).toEqual(
+      expect.arrayContaining(["abortAttach", "cancelReconnect", "disarmPoll"]),
+    );
+  });
+});

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

@@ -0,0 +1,600 @@
+/**
+ * Run-lifecycle finite state machine for a single AI-chat thread (#488).
+ *
+ * ============================================================================
+ * WHY THIS EXISTS
+ * ----------------------------------------------------------------------------
+ * The resume/reconnect/poll/stop/supersede lifecycle used to be spread across
+ * ~26 `useRef` one-shot flags in `chat-thread.tsx`, each disarmed "on every
+ * path". Ownerless flag combinations produced silent UI freezes, and every fix
+ * added another ref (the #381 -> #432 -> #456 spiral). This module replaces that
+ * ref-zoo with ONE pure reducer whose transitions are enumerable and unit-
+ * testable in isolation (event x state -> next state is the observable property).
+ *
+ * The reducer is PURE: it owns no timers, no fetches, no React state. It maps
+ * `(machine, event) -> machine`, where the returned machine carries the list of
+ * COMMAND EFFECTS to run for that transition. A thin runtime in `chat-thread.tsx`
+ * dispatches events (from SDK callbacks / HTTP outcomes) and executes the
+ * effects (attach GET, POST /stream, POST /run, POST /stop, backoff timers,
+ * poll arm/disarm). The runtime lives in a THREAD, not the window, so a late SDK
+ * callback dies with the owner (kills the "event from a dead view" class, #161).
+ *
+ * ============================================================================
+ * INVARIANTS (see run-fsm.spec.md for the full spec + tables)
+ * ----------------------------------------------------------------------------
+ *  I1  EPOCH (generation counter). Commands (`resumeStream`, `postRun`, `stop`,
+ *      `supersede`, `scheduleReconnect`) are async; their outcomes arrive on the
+ *      SAME SDK/HTTP callbacks. Every command-emitting transition increments
+ *      `ctx.epoch`; every OUTCOME event carries the epoch it was issued under;
+ *      the reducer DROPS an outcome whose epoch != the current epoch. This is
+ *      what the one-shot-ref zoo used to approximate by hand.
+ *  I2  OWNERSHIP is a CONTEXT FIELD (`'local' | 'observer'`), not a state —
+ *      orthogonal to the transport phase. The queue is flushed ONLY by a local
+ *      owner (an observer following a detached run never flushes).
+ *  I3  RUN-FACT ("a run is active") is first-class from the server: `runFact`
+ *      holds the server-confirmed active run id (POST /run on mount, the `start`
+ *      metadata runId, attach outcomes). Reconnect is entered by the RUN-FACT,
+ *      not by the presence of an assistant message (#488 commit 2). A fresh
+ *      negative fact (null) cancels reconnect immediately.
+ *  I4  Exit `stopping` by DATA (a terminal row / negative run-fact), NEVER by the
+ *      stopRun HTTP response (which returns after abort, before finalization).
+ *  I5  Command controllers are effect-owned (abort in cleanup), NOT render-phase
+ *      refs — expressed here as the `abortAttach` effect on disposing transitions.
+ * ============================================================================
+ */
+
+// ---------------------------------------------------------------------------
+// Phases (the transport lifecycle). Ownership / runFact are CONTEXT, not here.
+// ---------------------------------------------------------------------------
+
+/** Why the degraded poll is the active recovery. */
+export type PollReason =
+  | "attach-none" // mount attach returned 204 / error — nothing live to attach
+  | "starved" // a resumed finish carried no visible content
+  | "disconnect-visible" // a live disconnect WITH on-screen content — poll to terminal
+  | "reconnect-exhausted"; // the live re-attach ladder gave up
+
+/** The classified error kind (drives the banner text + composer behavior). */
+export type ErrorKind =
+  | "stream" // a generic provider/network stream error (useChat error)
+  | "run-already-active" // 409 A_RUN_ALREADY_ACTIVE (a plain POST hit the gate)
+  | "supersede-mismatch" // 409 SUPERSEDE_TARGET_MISMATCH (CAS target moved)
+  | "supersede-timeout" // 409 SUPERSEDE_TIMEOUT (old run did not settle in W)
+  | "supersede-invalid" // 409 SUPERSEDE_INVALID (bad supersede target)
+  | "begin-failed"; // 503 A_RUN_BEGIN_FAILED (could not start the run)
+
+export type Phase =
+  | { name: "idle" }
+  | { name: "sending" } // local POST in flight, before the first frame
+  | { name: "streaming" } // receiving frames
+  | { name: "attaching" } // mount-time attach GET in flight
+  | { name: "reconnecting"; attempt: number; failed: boolean }
+  | { name: "polling"; reason: PollReason }
+  | { name: "stalled" } // poll hit the inactivity cap — banner + Retry
+  | { name: "stopping" }
+  | { name: "superseding" }
+  | { name: "error"; kind: ErrorKind };
+
+export type Ownership = "local" | "observer";
+
+/** The server-confirmed active run, or null when no run is active. */
+export type RunFact = { runId: string } | null;
+
+export interface Ctx {
+  /** I1: generation counter — every command-transition increments it. */
+  epoch: number;
+  /** I2: does THIS client own the turn's writes (local streamer) or observe? */
+  ownership: Ownership;
+  /** I3: the server-confirmed active run. */
+  runFact: RunFact;
+  /**
+   * Are we FOLLOWING a live run we were locally streaming (the reconnect ladder),
+   * as opposed to a one-shot mount-attach resume? Both are `ownership: 'observer'`,
+   * but they recover DIFFERENTLY on a drop: a live-follow drop RE-ENTERS the
+   * reconnect ladder (#488 commit 3 — the second break after a successful re-attach
+   * must reconnect again, not fall to silent poll), while a mount-resume drop falls
+   * to the degraded poll. This is the ctx bit that separates the two WITHOUT a new
+   * component ref (it is why commit 3 needs the FSM, not a surgical patch).
+   */
+  liveFollow: boolean;
+}
+
+export interface Machine {
+  phase: Phase;
+  ctx: Ctx;
+  /** Command effects to run for the transition that produced THIS machine.
+   *  The runtime executes them and does not read them again. */
+  effects: Effect[];
+}
+
+// ---------------------------------------------------------------------------
+// Command effects (the reducer's only side-channel — executed by the runtime).
+// ---------------------------------------------------------------------------
+
+export type Effect =
+  /** POST /run to (re)establish or verify the run-fact. `reason` is diagnostic. */
+  | { type: "postRun"; reason: "mount" | "verify" }
+  /** Trigger the SDK `resumeStream()` (attach GET via prepareReconnectToStream). */
+  | { type: "resumeStream" }
+  /** Schedule a reconnect attempt after a backoff, then dispatch RECONNECT_ATTEMPT. */
+  | { type: "scheduleReconnect"; attempt: number; delayMs: number }
+  /** Cancel any pending reconnect backoff timer. */
+  | { type: "cancelReconnect" }
+  /** Arm the degraded poll (the window's dumb timer follows the run in the DB). */
+  | { type: "armPoll"; reason: PollReason }
+  /** Disarm the degraded poll. */
+  | { type: "disarmPoll" }
+  /** POST /stop the chat's active run (authoritative detached-run stop). */
+  | { type: "stopRun" }
+  /** POST /stream { supersede: { runId } } — the CAS "interrupt and send now". */
+  | { type: "supersede"; targetRunId: string }
+  /** Abort the in-flight attach/reconnect GET controller (dispose / observer stop). */
+  | { type: "abortAttach" };
+
+// ---------------------------------------------------------------------------
+// Events. An OUTCOME event MAY carry `epoch`; if it does and it does not equal
+// the current epoch, the reducer drops it (I1). Trigger events (user actions,
+// fresh disconnects) carry no epoch and are never dropped.
+// ---------------------------------------------------------------------------
+
+export type Event =
+  // -- local turn --
+  | { type: "SEND_LOCAL" }
+  | { type: "STREAM_START"; runId?: string; epoch?: number }
+  /** An OBSERVER's attached stream ended WITHOUT reaching terminal (a starved
+   *  clean replay, or a torn resume) — fall to the degraded poll to drive the row
+   *  to its real terminal state. (A live-follow drop uses FINISH_DISCONNECT.) */
+  | { type: "STREAM_INCOMPLETE"; reason: PollReason; epoch?: number }
+  | { type: "FINISH_CLEAN"; epoch?: number }
+  | { type: "FINISH_ABORT"; epoch?: number }
+  | { type: "FINISH_DISCONNECT"; hasVisibleContent: boolean; epoch?: number }
+  | { type: "FINISH_ERROR"; kind: ErrorKind; epoch?: number }
+  // -- mount attach (resume) --
+  | { type: "ATTACH_START"; runId?: string }
+  | { type: "ATTACH_LIVE"; epoch?: number }
+  | { type: "ATTACH_NONE"; epoch?: number }
+  // -- reconnect after a live disconnect (entered by FINISH_DISCONNECT, #488 c2) --
+  | { type: "RECONNECT_ATTEMPT"; attempt: number; epoch?: number }
+  | { type: "RECONNECT_ATTACHED"; epoch?: number }
+  | { type: "RECONNECT_NONE"; epoch?: number }
+  | { type: "RETRY" }
+  // -- degraded poll --
+  | { type: "POLL_TERMINAL" }
+  | { type: "POLL_IDLE_CAP" }
+  // -- run-fact (server-confirmed active run) --
+  | { type: "RUN_FACT"; runFact: RunFact; epoch?: number }
+  // -- stop --
+  | { type: "STOP_REQUESTED" }
+  // -- supersede (CAS) --
+  | { type: "SUPERSEDE_REQUESTED"; targetRunId: string }
+  | { type: "SUPERSEDE_READY"; runId?: string; epoch?: number }
+  | { type: "SUPERSEDE_MISMATCH"; currentRunId?: string; epoch?: number }
+  | { type: "SUPERSEDE_TIMEOUT"; epoch?: number }
+  | { type: "SUPERSEDE_INVALID"; epoch?: number }
+  | { type: "RUN_ALREADY_ACTIVE"; activeRunId?: string }
+  // -- lifecycle --
+  | { type: "DISPOSE" };
+
+export const RECONNECT_MAX_ATTEMPTS = 5;
+export const RECONNECT_BASE_DELAY_MS = 1000;
+/** Backoff before attempt N (1-based): 1s, 2s, 4s, 8s, 16s. */
+export function reconnectDelayMs(attempt: number): number {
+  return RECONNECT_BASE_DELAY_MS * 2 ** (attempt - 1);
+}
+
+// ---------------------------------------------------------------------------
+// Constructors / helpers.
+// ---------------------------------------------------------------------------
+
+export function initialMachine(overrides?: Partial<Ctx>): Machine {
+  return {
+    phase: { name: "idle" },
+    ctx: { epoch: 0, ownership: "local", runFact: null, liveFollow: false, ...overrides },
+    effects: [],
+  };
+}
+
+/** Build a machine result: a phase, optional ctx patch, and effects. Empty
+ *  effects by default. Never mutates the input. */
+function to(
+  m: Machine,
+  phase: Phase,
+  opts?: { ctx?: Partial<Ctx>; effects?: Effect[] },
+): Machine {
+  return {
+    phase,
+    ctx: { ...m.ctx, ...(opts?.ctx ?? {}) },
+    effects: opts?.effects ?? [],
+  };
+}
+
+/** No transition: keep the phase, clear effects (so a re-run does not re-fire). */
+function stay(m: Machine): Machine {
+  return { phase: m.phase, ctx: m.ctx, effects: [] };
+}
+
+/** A command-transition: same as `to` but bumps the epoch (I1). Any outcome
+ *  event issued under the old epoch is dropped once this lands. */
+function command(
+  m: Machine,
+  phase: Phase,
+  effects: Effect[],
+  ctx?: Partial<Ctx>,
+): Machine {
+  return {
+    phase,
+    ctx: { ...m.ctx, ...(ctx ?? {}), epoch: m.ctx.epoch + 1 },
+    effects,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The pure reducer.
+// ---------------------------------------------------------------------------
+
+/** The terminal stream-finish events (one turn's stream ended). */
+function isFinishEvent(event: Event): boolean {
+  return (
+    event.type === "FINISH_ABORT" ||
+    event.type === "FINISH_CLEAN" ||
+    event.type === "FINISH_DISCONNECT" ||
+    event.type === "FINISH_ERROR" ||
+    event.type === "STREAM_INCOMPLETE"
+  );
+}
+
+export function reduce(m: Machine, event: Event): Machine {
+  // MEDIUM (#488 re-review): honor ANY stream finish in `stopping` regardless of
+  // generation. A plain user Stop has NO successor stream — the aborted stream's
+  // finish IS the expected end of the stop, so exit `stopping -> idle` by that DATA
+  // (I4). The epoch filter below must NOT drop it: STOP_REQUESTED bumped the epoch,
+  // but the finish carries the PRE-stop generation (the runtime stamps it with the
+  // stream's start epoch), so I1 would otherwise strand the machine in `stopping`
+  // forever (no idle-cap covers `stopping`). The epoch filter stays in force for
+  // `superseding` (a successor B owns) — that is the F1 supersede drop.
+  if (m.phase.name === "stopping" && isFinishEvent(event)) {
+    return to(m, { name: "idle" }, {
+      // Reset ownership to local on this terminal transition (review #2): otherwise
+      // an observer-stop leaves ownership 'observer' and hides "Send now" forever.
+      ctx: { runFact: null, liveFollow: false, ownership: "local" },
+      effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
+    });
+  }
+
+  // I1: drop a stale outcome (an event issued under a superseded epoch).
+  if ("epoch" in event && event.epoch !== undefined && event.epoch !== m.ctx.epoch) {
+    return stay(m);
+  }
+
+  switch (event.type) {
+    // ---- local turn ----------------------------------------------------
+    case "SEND_LOCAL":
+      // A local send owns the view: leave any recovery, become the local
+      // streamer, disarm poll/reconnect. epoch++ so a late recovery outcome
+      // from the previous phase is dropped.
+      return command(
+        m,
+        { name: "sending" },
+        [{ type: "cancelReconnect" }, { type: "disarmPoll" }],
+        { ownership: "local", liveFollow: false },
+      );
+
+    case "STREAM_INCOMPLETE":
+      // An OBSERVER's attached stream ended incomplete (starved / torn) — follow
+      // the run to terminal via the degraded poll.
+      return to(m, { name: "polling", reason: event.reason }, {
+        effects: [{ type: "armPoll", reason: event.reason }],
+      });
+
+    case "STREAM_START": {
+      // First frame arrived. Adopt the run-fact runId if present. sending ->
+      // streaming; a reconnect/attach that just went live also lands here.
+      const runFact = event.runId ? { runId: event.runId } : m.ctx.runFact;
+      return to(m, { name: "streaming" }, {
+        ctx: { runFact },
+        effects: [{ type: "cancelReconnect" }, { type: "disarmPoll" }],
+      });
+    }
+
+    case "FINISH_CLEAN":
+      // A clean terminal outcome. The run is done — clear the run-fact and go
+      // idle. (The queue flush is a component concern gated by ownership; the
+      // FSM only models the phase.) Review #2: reset ownership to local so a
+      // just-finished observer-attach turn re-exposes "Send now" for the queue.
+      return to(m, { name: "idle" }, {
+        ctx: { runFact: null, liveFollow: false, ownership: "local" },
+        effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
+      });
+
+    case "FINISH_ABORT":
+      // A user Stop / intentional abort finished. If we were stopping, the
+      // terminal data has now arrived (I4) — go idle. The run-fact is cleared.
+      return to(m, { name: "idle" }, {
+        ctx: { runFact: null, liveFollow: false, ownership: "local" },
+        effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
+      });
+
+    case "FINISH_DISCONNECT":
+      // A LIVE SSE drop. Recovery depends on WHO we are (I2 + liveFollow):
+      //  - a mount-attach OBSERVER (a one-shot resume, NOT live-follow) that drops
+      //    -> the degraded poll drives the row to terminal from the DB.
+      if (m.ctx.ownership === "observer" && !m.ctx.liveFollow) {
+        return to(m, { name: "polling", reason: "disconnect-visible" }, {
+          effects: [{ type: "armPoll", reason: "disconnect-visible" }],
+        });
+      }
+      //  - a LOCAL live turn (first drop) OR a live-follow re-attach (a SUBSEQUENT
+      //    drop) -> (re-)enter the reconnect ladder. #488 commit 3: allowed
+      //    REPEATEDLY — `liveFollow` is kept across a successful re-attach, so the
+      //    second break reconnects again instead of falling to silent poll.
+      // #488 commit 2: gated on the RUN-FACT (or an existing live-follow), NOT on
+      // the presence of an assistant message — a setup-phase break still recovers.
+      //  - visible content already on screen -> keep it, ALSO poll to terminal
+      //    (a full replay could clobber the fuller live tail);
+      //  - no visible content -> the reconnect ladder rebuilds it.
+      if (m.ctx.runFact || m.ctx.liveFollow) {
+        const effects: Effect[] = [
+          { type: "scheduleReconnect", attempt: 1, delayMs: reconnectDelayMs(1) },
+        ];
+        if (event.hasVisibleContent) effects.push({ type: "armPoll", reason: "disconnect-visible" });
+        return command(m, { name: "reconnecting", attempt: 1, failed: false }, effects, {
+          ownership: "observer",
+          liveFollow: true,
+        });
+      }
+      // No run to recover: a plain disconnect. Surface the terminal notice.
+      return to(m, { name: "idle" }, {
+        ctx: { runFact: null, liveFollow: false, ownership: "local" },
+      });
+
+    case "FINISH_ERROR":
+      return to(m, { name: "error", kind: event.kind }, {
+        ctx: { runFact: null, liveFollow: false, ownership: "local" },
+        effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
+      });
+
+    // ---- mount attach (resume) ----------------------------------------
+    case "ATTACH_START":
+      // A reopened tab attaches to a still-running run: observer ownership.
+      // #488 F2: ONLY from idle. The mount `getRun` round-trip resolves async, and
+      // a local send may have started meanwhile (phase `sending`, ownership local);
+      // a late ATTACH_START must NOT hijack that local turn into an observer-attach
+      // (queue would stop flushing, "Send now" would hide). Guarding in the reducer
+      // covers every dispatch source.
+      if (m.phase.name !== "idle") return stay(m);
+      return command(m, { name: "attaching" }, [{ type: "resumeStream" }], {
+        ownership: "observer",
+        runFact: event.runId ? { runId: event.runId } : m.ctx.runFact,
+      });
+
+    case "ATTACH_LIVE":
+      // The attach GET returned a live 2xx stream — follow it as an observer.
+      // Review #1: guard by SOURCE phase. The epoch filter alone is not enough — a
+      // POLL_TERMINAL uses to() (no epoch bump) and does not abort the in-flight
+      // GET, so a slow 2xx landing after the machine already left `attaching` (e.g.
+      // the armed poll saw the terminal row -> idle) would resurrect a settled run
+      // into a phantom `streaming`. Only enter streaming FROM `attaching`.
+      if (m.phase.name !== "attaching") return stay(m);
+      return to(m, { name: "streaming" });
+
+    case "ATTACH_NONE":
+      // 204 / non-2xx / throw: nothing live to attach. Arm the degraded poll to
+      // follow the run to terminal from the DB. This is a soft-negative run-fact
+      // (204 on a non-stripped path is authoritative-negative; the runtime may
+      // pass a RUN_FACT null separately). Keep the run-fact as-is here.
+      // Review #1: guard by source phase for consistency (a late outcome after the
+      // machine already left `attaching` must not re-arm a poll).
+      if (m.phase.name !== "attaching") return stay(m);
+      return to(m, { name: "polling", reason: "attach-none" }, {
+        effects: [{ type: "armPoll", reason: "attach-none" }],
+      });
+
+    // ---- reconnect after a live disconnect ----------------------------
+    case "RECONNECT_ATTEMPT":
+      // A scheduled backoff fired — fire the attach GET. epoch++ so the previous
+      // attempt's late outcome cannot drive this one.
+      if (m.phase.name !== "reconnecting") return stay(m);
+      return command(
+        m,
+        { name: "reconnecting", attempt: event.attempt, failed: false },
+        [{ type: "resumeStream" }],
+      );
+
+    case "RECONNECT_ATTACHED":
+      // #488 commit 3: a live re-attach succeeded. Reset to streaming — the
+      // attempt counter is dropped, so a LATER disconnect can start a fresh
+      // ladder from attempt 1 (the old one-shot `!wasResumed` gate forbade a
+      // second cycle, sending the second break to silent poll).
+      // Review #1: guard by SOURCE phase. The armed degraded poll can reach the
+      // terminal row (POLL_TERMINAL -> idle, via to(), NO epoch bump, GET not
+      // aborted) BEFORE a slow reconnect GET returns 2xx; without this guard that
+      // late RECONNECT_ATTACHED (same epoch) would resurrect a settled run into a
+      // phantom `streaming`. Only re-enter streaming FROM `reconnecting`.
+      if (m.phase.name !== "reconnecting") return stay(m);
+      return to(m, { name: "streaming" }, {
+        effects: [{ type: "cancelReconnect" }, { type: "disarmPoll" }],
+      });
+
+    case "RECONNECT_NONE": {
+      // 204 / error during a reconnect attempt. Arm the degraded poll as the
+      // belt-and-suspenders fallback, then either back off to the next attempt
+      // or, at the cap, surface the manual Retry ("failed").
+      if (m.phase.name !== "reconnecting") return stay(m);
+      const attempt = m.phase.attempt;
+      if (attempt < RECONNECT_MAX_ATTEMPTS) {
+        return command(
+          m,
+          { name: "reconnecting", attempt: attempt + 1, failed: false },
+          [
+            { type: "armPoll", reason: "attach-none" },
+            { type: "scheduleReconnect", attempt: attempt + 1, delayMs: reconnectDelayMs(attempt + 1) },
+          ],
+        );
+      }
+      return to(m, { name: "reconnecting", attempt, failed: true }, {
+        effects: [{ type: "armPoll", reason: "reconnect-exhausted" }],
+      });
+    }
+
+    case "RETRY":
+      // Manual Retry from the "failed" reconnect banner OR the stalled banner.
+      if (m.phase.name === "reconnecting" && m.phase.failed) {
+        return command(
+          m,
+          { name: "reconnecting", attempt: 1, failed: false },
+          [{ type: "resumeStream" }],
+        );
+      }
+      if (m.phase.name === "stalled") {
+        // Re-arm the poll to try to catch the run up again.
+        return command(m, { name: "polling", reason: "attach-none" }, [
+          { type: "armPoll", reason: "attach-none" },
+        ]);
+      }
+      return stay(m);
+
+    // ---- degraded poll -------------------------------------------------
+    case "POLL_TERMINAL":
+      // The run reached a terminal row via the poll (or the reconcile merge). Go
+      // idle and disarm everything (I4: this is a DATA-driven exit, incl. exit
+      // from `stopping`). Review #2: reset ownership to local.
+      return to(m, { name: "idle" }, {
+        ctx: { runFact: null, liveFollow: false, ownership: "local" },
+        effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
+      });
+
+    case "POLL_IDLE_CAP":
+      // Review #4: `stopping` also arms the poll (STOP_REQUESTED) but has NO other
+      // backstop — an observer-stop with no SDK stream to fire onFinish, whose
+      // server stop never drives the run terminal, would poll the DB forever. Give
+      // it a bounded exit: cap -> idle + disarm (NOT `stalled`; Stop was already
+      // pressed, so there is nothing for the user to retry).
+      if (m.phase.name === "stopping") {
+        return to(m, { name: "idle" }, {
+          ctx: { runFact: null, liveFollow: false, ownership: "local" },
+          effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
+        });
+      }
+      // #488 commit 4a: the poll hit the inactivity cap. Instead of going SILENT
+      // (the old "forever half-done answer"), surface a stalled banner + Retry.
+      if (m.phase.name !== "polling" && m.phase.name !== "reconnecting") return stay(m);
+      return to(m, { name: "stalled" }, {
+        effects: [{ type: "disarmPoll" }, { type: "cancelReconnect" }],
+      });
+
+    // ---- run-fact ------------------------------------------------------
+    case "RUN_FACT": {
+      const runFact = event.runFact;
+      // A fresh NEGATIVE fact (no active run) cancels recovery immediately (I3):
+      // there is nothing to reconnect to / poll for.
+      if (!runFact) {
+        if (
+          m.phase.name === "reconnecting" ||
+          m.phase.name === "attaching" ||
+          m.phase.name === "polling" ||
+          m.phase.name === "stopping"
+        ) {
+          return to(m, { name: "idle" }, {
+            // Review #2: reset ownership to local on this terminal transition.
+            ctx: { runFact: null, liveFollow: false, ownership: "local" },
+            effects: [{ type: "cancelReconnect" }, { type: "disarmPoll" }],
+          });
+        }
+        return to(m, m.phase, { ctx: { runFact: null } });
+      }
+      // A positive fact just updates the context (pessimism toward an attempt: a
+      // stale-but-positive fact permits entering recovery; a 204 will cut it).
+      return to(m, m.phase, { ctx: { runFact } });
+    }
+
+    // ---- stop ----------------------------------------------------------
+    case "STOP_REQUESTED":
+      // Authoritative stop of a detached run. Enter `stopping` and fire stopRun +
+      // abort the local/attach reader. ALSO arm the poll so the terminal row is
+      // observed — the exit is by DATA (I4: a terminal row / negative run-fact),
+      // never by the stopRun HTTP response (which returns after abort, before
+      // finalization). For a local turn the aborted stream's onFinish (ANY finish)
+      // is HONORED in `stopping` at the top of reduce() — regardless of generation
+      // — and exits to idle; the armed poll is the fallback for an observer stop
+      // with no local onFinish.
+      return command(
+        m,
+        { name: "stopping" },
+        [
+          { type: "stopRun" },
+          { type: "abortAttach" },
+          { type: "cancelReconnect" },
+          { type: "armPoll", reason: "attach-none" },
+        ],
+      );
+
+    // ---- supersede (CAS) ----------------------------------------------
+    case "SUPERSEDE_REQUESTED":
+      // "Interrupt and send now": CAS POST /stream { supersede }. epoch++ so a
+      // late outcome of the interrupted run is dropped.
+      return command(
+        m,
+        { name: "superseding" },
+        [{ type: "supersede", targetRunId: event.targetRunId }, { type: "cancelReconnect" }, { type: "disarmPoll" }],
+      );
+
+    case "SUPERSEDE_READY": {
+      // CAS succeeded (old run stopped/settled, slot taken, new run begun). We
+      // are now the local streamer of the NEW run. Adopt its runId if provided.
+      const runFact = event.runId ? { runId: event.runId } : m.ctx.runFact;
+      return to(m, { name: "streaming" }, {
+        ctx: { ownership: "local", runFact, liveFollow: false },
+      });
+    }
+
+    case "SUPERSEDE_MISMATCH":
+      // The active run moved between the click and the CAS. Per the spec: verify
+      // via /run rather than blindly banner — the mismatch may be our own already-
+      // superseded run. Surface a classified error AND fire a run-fact verify.
+      return to(m, { name: "error", kind: "supersede-mismatch" }, {
+        ctx: { runFact: event.currentRunId ? { runId: event.currentRunId } : m.ctx.runFact },
+        effects: [{ type: "postRun", reason: "verify" }],
+      });
+
+    case "SUPERSEDE_TIMEOUT":
+      // The old run did not settle within W. Nothing persisted; the composer keeps
+      // its text. Classified error, NO auto-retry (the old client retry ladder is
+      // removed in #488 commit 5).
+      return to(m, { name: "error", kind: "supersede-timeout" });
+
+    case "SUPERSEDE_INVALID":
+      return to(m, { name: "error", kind: "supersede-invalid" });
+
+    case "RUN_ALREADY_ACTIVE":
+      // A plain POST hit the one-active-run gate. NO auto-retry — the composer
+      // offers "interrupt and send" (supersede) instead. #497/S4: adopt the
+      // server's activeRunId as the run-fact so that supersede can TARGET the
+      // (possibly foreign-tab) active run via the CAS, rather than a blind
+      // promote+abort that just 409s again. A stale/absent id keeps the prior fact.
+      return to(m, { name: "error", kind: "run-already-active" }, {
+        ctx: { runFact: event.activeRunId ? { runId: event.activeRunId } : m.ctx.runFact },
+      });
+
+    // ---- lifecycle -----------------------------------------------------
+    case "DISPOSE":
+      // Unmount: abort in-flight controllers, drop timers, and bump the epoch so
+      // NO late callback can drive this (now dead) machine (I5).
+      return command(
+        m,
+        { name: "idle" },
+        [
+          { type: "abortAttach" },
+          { type: "cancelReconnect" },
+          { type: "disarmPoll" },
+        ],
+        { liveFollow: false },
+      );
+
+    default: {
+      // Exhaustiveness guard.
+      const _never: never = event;
+      void _never;
+      return stay(m);
+    }
+  }
+}

apps/client/src/features/ai-chat/utils/adopt-chat-id.test.ts

@@ -3,6 +3,7 @@ import {
   resolveAdoptedChatId,
   newlyAddedChatIds,
   extractServerChatId,
+  extractRunId,
 } from "./adopt-chat-id";
 
 describe("resolveAdoptedChatId", () => {
@@ -70,3 +71,17 @@ describe("extractServerChatId", () => {
     expect(extractServerChatId(undefined)).toBeUndefined();
   });
 });
+
+describe("extractRunId", () => {
+  it("reads a string runId from the start metadata", () => {
+    expect(extractRunId({ metadata: { runId: "run-1" } })).toBe("run-1");
+  });
+  it("returns undefined when runId is absent", () => {
+    expect(extractRunId({ metadata: { chatId: "c" } })).toBeUndefined();
+    expect(extractRunId({})).toBeUndefined();
+    expect(extractRunId(undefined)).toBeUndefined();
+  });
+  it("returns undefined for a non-string runId", () => {
+    expect(extractRunId({ metadata: { runId: 7 } })).toBeUndefined();
+  });
+});

apps/client/src/features/ai-chat/utils/adopt-chat-id.ts

@@ -56,6 +56,20 @@ export function extractServerChatId(
   return typeof m?.chatId === "string" ? m.chatId : undefined;
 }
 
+/**
+ * #488: read the authoritative RUN id off a streaming assistant message. The
+ * server attaches it as `message.metadata.runId` on the `start` part when a run
+ * wraps the turn (see server `chatStreamMetadata`, #184/#487). This is the live
+ * run-fact update the client FSM adopts (mirrors `extractServerChatId`). Returns
+ * it only when it is a string; undefined otherwise.
+ */
+export function extractRunId(
+  message: { metadata?: unknown } | undefined,
+): string | undefined {
+  const m = message?.metadata as { runId?: string } | undefined;
+  return typeof m?.runId === "string" ? m.runId : undefined;
+}
+
 /**
  * The deduped set of ids present in `afterIds` but not in `beforeIds`. A
  * paginated/flatMapped list can repeat the same id, so dedupe: one genuinely-new

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

@@ -6,13 +6,10 @@ describe("estimateTokens", () => {
     expect(estimateTokens("")).toBe(0);
   });
 
-  // #490: migrated onto the shared @docmost/token-estimate module (chars/2.5, up
+  it("ceils chars/4 so any non-empty text is at least 1 token", () => {
-  // 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("ab")).toBe(1);
+    expect(estimateTokens("abcd")).toBe(1);
-    expect(estimateTokens("abcde")).toBe(2); // 5 / 2.5 = 2
+    expect(estimateTokens("abcde")).toBe(2);
-    expect(estimateTokens("x".repeat(10))).toBe(4); // 10 / 2.5 = 4
+    expect(estimateTokens("12345678")).toBe(2);
   });
 });

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

@@ -2,10 +2,18 @@
  * 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. This re-exports the SHARED estimator from
+ * is a CLIENT ESTIMATE (chars/≈4 heuristic). Pure + unit-testable: it never runs
- * `@docmost/token-estimate` (chars/2.5) so the in-body counter and the server's
+ * a real BPE tokenizer (that would be O(n²) on the hot path, bloat the bundle,
- * replay budgeter use the SAME heuristic — two divergent estimators would mean
+ * and be wrong for Gemini/Ollama anyway). Used by the in-body reasoning counter
- * "the badge shows 60%" while "the budgeter already trimmed" (#490). Used by the
+ * ("Thinking · N tokens").
- * in-body reasoning counter ("Thinking · N tokens").
  */
-export { estimateTokens } from "@docmost/token-estimate";
+
+/**
+ * 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);
+}

apps/client/src/features/ai-chat/utils/error-message.test.ts

@@ -42,6 +42,53 @@ describe("describeChatError", () => {
     );
   });
 
+  // #488 commit 5: the #487 concurrency-gate / supersede 409s. FULL real bodies:
+  // a ConflictException(object) whose response is serialized verbatim, carrying a
+  // `code` and statusCode 409. Each must classify to a human text, not raw JSON.
+  it("classifies A_RUN_ALREADY_ACTIVE (409) as already-answering, not raw JSON", () => {
+    const body =
+      '{"message":"A run is already active for this chat","code":"A_RUN_ALREADY_ACTIVE","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe(
+      "The agent is already answering",
+    );
+    // Never leaks the raw code as the detail.
+    expect(describeChatError(body, t).detail).not.toContain("A_RUN_ALREADY_ACTIVE");
+  });
+
+  it("classifies SUPERSEDE_TARGET_MISMATCH (409) as run-changed", () => {
+    // Real server body shape: the current run id is `activeRunId` (NOT `runId`) —
+    // see ai-chat.controller.ts. describeChatError classifies off `code` only.
+    const body =
+      '{"message":"active run does not match the supersede target","code":"SUPERSEDE_TARGET_MISMATCH","activeRunId":"run-x","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe(
+      "Couldn't interrupt — the run changed",
+    );
+  });
+
+  it("classifies SUPERSEDE_TIMEOUT (409) as couldn't-interrupt-in-time", () => {
+    const body =
+      '{"message":"the run did not settle within the supersede window","code":"SUPERSEDE_TIMEOUT","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe("Couldn't interrupt in time");
+  });
+
+  it("classifies SUPERSEDE_INVALID (409) as couldn't-interrupt-that-run", () => {
+    const body =
+      '{"message":"supervise requires chatId","code":"SUPERSEDE_INVALID","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe(
+      "Couldn't interrupt that run",
+    );
+  });
+
+  it("ORDER GUARD: A_RUN_ALREADY_ACTIVE wins over any generic status branch", () => {
+    // Even though the body could superficially look 4xx-ish, the code branch runs
+    // first, so it is never mislabeled by a generic status heading.
+    const body =
+      '{"message":"conflict","code":"A_RUN_ALREADY_ACTIVE","statusCode":409}';
+    const view = describeChatError(body, t);
+    expect(view.title).not.toBe("Something went wrong");
+    expect(view.title).not.toBe("AI provider not configured");
+  });
+
   it("classifies a dropped connection (ECONNRESET) as a lost-connection error", () => {
     expect(
       describeChatError("Cannot connect to API: read ECONNRESET", t).title,

apps/client/src/features/ai-chat/utils/error-message.ts

@@ -39,6 +39,44 @@ export function describeChatError(
     };
   }
 
+  // #488 commit 5: the #487 concurrency-gate / supersede 409s. These arrive as a
+  // ConflictException(object) body carrying a `code` (and statusCode 409). They
+  // MUST be classified by `code` STRICTLY BEFORE any generic status branch, or the
+  // user sees the raw JSON `{"code":"A_RUN_ALREADY_ACTIVE",…}`. The code strings
+  // are the real #487 server contract (ai-chat.controller.ts) — do not invent.
+  if (/"code"\s*:\s*"A_RUN_ALREADY_ACTIVE"/.test(msg)) {
+    return {
+      title: t("The agent is already answering"),
+      detail: t(
+        "This chat already has a run in progress. Wait for it to finish, or interrupt it and send now.",
+      ),
+    };
+  }
+  if (/"code"\s*:\s*"SUPERSEDE_TARGET_MISMATCH"/.test(msg)) {
+    return {
+      title: t("Couldn't interrupt — the run changed"),
+      detail: t(
+        "The run you tried to interrupt is no longer the active one. Check the latest answer and try again.",
+      ),
+    };
+  }
+  if (/"code"\s*:\s*"SUPERSEDE_TIMEOUT"/.test(msg)) {
+    return {
+      title: t("Couldn't interrupt in time"),
+      detail: t(
+        "The previous run didn't stop in time. Nothing was sent — try sending again.",
+      ),
+    };
+  }
+  if (/"code"\s*:\s*"SUPERSEDE_INVALID"/.test(msg)) {
+    return {
+      title: t("Couldn't interrupt that run"),
+      detail: t(
+        "The run to interrupt doesn't belong to this chat. Reload and try again.",
+      ),
+    };
+  }
+
   if (/"statusCode"\s*:\s*403\b/.test(msg)) {
     return {
       title: t("AI chat is disabled"),

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 && pnpm --filter @docmost/token-estimate build",
+    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",
@@ -44,7 +44,6 @@
     "@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",
@@ -207,7 +206,6 @@
       "^@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.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, aiChatMessageRepo };
+    return { svc };
   }
 
   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, aiChatMessageRepo } = makeService();
+    const { svc } = 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, aiChatMessageRepo };
+    return { capturedOpts, runHooks };
   }
 
   it('F9: onStepFinish bumps the run step count, onFinish settles the run "completed" (the dominant autonomous-run path)', async () => {
@@ -369,51 +369,6 @@ 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,7 +13,6 @@ import {
   compactToolOutput,
   assistantParts,
   serializeSteps,
-  type StepPartsCache,
   rowToUiMessage,
   prepareAgentStep,
   stepBudgetWarning,
@@ -29,9 +28,6 @@ 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';
@@ -118,54 +114,6 @@ 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 = [
       {
@@ -283,299 +231,61 @@ describe('assistantParts', () => {
   });
 });
 
-// #490 trace format v2: per call the trace stores { input } for the call and an
+describe('serializeSteps', () => {
-// 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('pairs a successful call with an { ok: true } outcome and NO output', () => {
+  it('flattens calls and results into a compact trace', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: { id: 'p1' } }],
+        toolCalls: [{ toolName: 'getPage', input: { id: 'p1' } }],
-        toolResults: [{ toolCallId: 'c1', toolName: 'getPage' }],
+        toolResults: [{ toolName: 'getPage', output: { title: 'T' } }],
       },
     ]) as Array<Record<string, unknown>>;
     expect(trace).toHaveLength(2);
     expect(trace[0]).toEqual({ toolName: 'getPage', input: { id: 'p1' } });
-    expect(trace[1]).toEqual({ toolName: 'getPage', ok: true });
+    expect(trace[1]).toEqual({ toolName: 'getPage', output: { title: 'T' } });
-    // 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 failure with { error, kind: "thrown" }', () => {
+  it('records a THROWN tool failure (tool-error part) with its error message', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [
+        toolCalls: [{ toolName: 'editPageText', input: { id: 'p1' } }],
-          { 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('marks an interrupted call (no result, no throw) with kind "interrupted"', () => {
+  it('truncates a very long tool-error message to the tool-output limit', () => {
-    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: [{ toolCallId: 'c1', toolName: 'editPageText', input: {} }],
+        toolCalls: [{ toolName: 'editPageText', input: {} }],
         toolResults: [],
-        content: [
+        content: [{ type: 'tool-error', toolName: 'editPageText', error: long }],
-          {
-            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);
-  });
 });
 
 describe('rowToUiMessage', () => {
@@ -908,23 +618,6 @@ 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,12 +55,6 @@ import {
   type SelectionContext,
 } from './tools/current-page.util';
 import { roleModelOverride } from './roles/role-model-config';
-import {
-  resolveReplayBudget,
-  isContextOverflowError,
-  trimHistoryForReplay,
-  REPLAY_AGGRESSIVE_FRACTION,
-} from './history-budget';
 import {
   startSseHeartbeat,
   stripStreamingHopByHopHeaders,
@@ -133,15 +127,6 @@ 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
@@ -897,21 +882,6 @@ 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,
@@ -951,17 +921,10 @@ 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
@@ -1123,7 +1086,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).
-      let messages = await convertHistoryResilient(uiMessages, (index, err) =>
+      const 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'
@@ -1172,58 +1135,6 @@ 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 =
-        priorOverflowed && replayBudget.thresholdTokens != null
-          ? Math.floor(
-              replayBudget.thresholdTokens * REPLAY_AGGRESSIVE_FRACTION,
-            )
-          : replayBudget.thresholdTokens;
-      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
@@ -1415,19 +1326,10 @@ 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
@@ -1437,39 +1339,6 @@ 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
@@ -1478,11 +1347,6 @@ 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
@@ -1552,10 +1416,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
           await this.aiChatMessageRepo.update(
             assistantId,
             workspace.id,
-            flushAssistant(capturedSteps, '', 'streaming', {
+            flushAssistant(capturedSteps, '', 'streaming', { pageChanged }),
-              pageChanged,
-              partsCache,
-            }),
             { onlyIfStreaming: true },
           );
         } catch (err) {
@@ -1788,8 +1649,6 @@ 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).
@@ -1814,8 +1673,6 @@ 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
@@ -1839,16 +1696,7 @@ 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 };
-            // #490 reactive branch: classify a CONTEXT-OVERFLOW rejection (the
+            const errorText = describeProviderError(error, String(error));
-            // 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.
@@ -1866,9 +1714,6 @@ 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.
@@ -1878,8 +1723,6 @@ 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
@@ -1894,7 +1737,6 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 flushAssistant(capturedSteps, truncated, 'error', {
                   error: OUTPUT_DEGENERATION_ERROR,
                   pageChanged,
-                  partsCache,
                 }),
               );
               if (runId)
@@ -1905,8 +1747,6 @@ 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 =
@@ -1931,7 +1771,6 @@ 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
@@ -1942,8 +1781,6 @@ 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();
           },
         });
 
@@ -2254,70 +2091,6 @@ 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,
@@ -2379,15 +2152,6 @@ 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
@@ -2595,97 +2359,71 @@ 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 ?? []) {
-    // Memoize per step object (#490): a finished step is immutable and keeps its
+    if (step.text) {
-    // reference across flushes, so its parts (and the costly output stringify) are
+      parts.push({ type: 'text', text: step.text });
-    // built exactly once per turn. A cache miss (or no cache) just rebuilds.
+      sawText = true;
-    let stepParts = cache?.get(step as object);
+    }
-    if (!stepParts) {
+    // Index this step's results by tool call id to pair calls with outputs.
-      stepParts = buildStepParts(step);
+    const resultsById = new Map<string, unknown>();
-      cache?.set(step as object, stepParts);
+    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.',
+        });
+      }
     }
-    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.
@@ -2848,16 +2586,6 @@ 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 ?? [];
@@ -2867,20 +2595,13 @@ 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(
+  const parts = assistantParts(finished, '') as unknown as Array<
-    finished,
+    Record<string, unknown>
-    '',
+  >;
-    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,
   };
   // finishReason: prefer an explicit one; else derive a sensible value from the
   // terminal status (so onError/onAbort records keep their historical reason).
@@ -2896,9 +2617,6 @@ 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
@@ -2924,85 +2642,42 @@ export function flushAssistant(
 
 /**
  * Reduce SDK step objects to a compact, JSON-serializable trace for the
- * `tool_calls` column — trace format **v2** (#490).
+ * `tool_calls` column. Stores only what the UI action-log and history need —
- *
+ * never raw provider payloads or keys.
- * 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<{
+    toolCalls?: ReadonlyArray<{ toolName?: string; input?: unknown }>;
-      toolCallId?: string;
+    toolResults?: ReadonlyArray<{ toolName?: string; output?: unknown }>;
-      toolName?: string;
-      input?: unknown;
-    }>;
-    toolResults?: ReadonlyArray<{ toolCallId?: string; toolName?: string }>;
     content?: ReadonlyArray<{
       type?: string;
-      toolCallId?: string;
       toolName?: string;
       error?: unknown;
     }>;
   }>,
 ): unknown {
-  const calls: Array<
+  const calls: Array<{
-    | { toolName?: string; input?: unknown }
+    toolName?: string;
-    | { toolName?: string; ok: true }
+    input?: unknown;
-    | { toolName?: string; error: string; kind: 'thrown' | 'interrupted' }
+    output?: unknown;
-  > = [];
+    error?: string;
+  }> = [];
   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 });
-      if (call.toolCallId && resultIds.has(call.toolCallId)) {
+    }
-        // Success: the output itself lives in metadata.parts, not here.
+    for (const r of step.toolResults ?? []) {
-        calls.push({ toolName: call.toolName, ok: true });
+      calls.push({ toolName: r.toolName, output: compactToolOutput(r.output) });
-      } else if (call.toolCallId && errorsById.has(call.toolCallId)) {
+    }
-        // Hard fail: the tool threw. Persist the real (bounded) reason.
+    // 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') {
         calls.push({
-          toolName: call.toolName,
+          toolName: part.toolName,
-          error: normalizeToolError(errorsById.get(call.toolCallId)),
+          error: normalizeToolError(part.error),
-          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.write-volume.spec.ts

@@ -1,209 +0,0 @@
-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/history-budget.spec.ts

@@ -1,266 +0,0 @@
-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 min(default, 0.7 x window) for a configured window', () => {
-    // 0.7 x 60k = 42k < 100k
-    expect(resolveReplayBudget(60_000)).toEqual({
-      thresholdTokens: 42_000,
-      usedDefault: false,
-    });
-    // 0.7 x 1M = 700k, capped to the 100k default
-    expect(resolveReplayBudget(1_000_000)).toEqual({
-      thresholdTokens: REPLAY_BUDGET_DEFAULT_TOKENS,
-      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

@@ -1,356 +0,0 @@
-/**
- * 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  -> `min(default, floor(fraction × window))`
- *  - 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.min(
-      REPLAY_BUDGET_DEFAULT_TOKENS,
-      Math.floor(REPLAY_BUDGET_WINDOW_FRACTION * n),
-    ),
-    usedDefault: false,
-  };
-}
-
-/**
- * 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

@@ -1,24 +0,0 @@
-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/types/db.d.ts

@@ -606,9 +606,6 @@ 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,9 +245,6 @@ 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,10 +105,6 @@ 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

docs/reading-ai-logs.md

@@ -8,35 +8,19 @@ 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_*`.
-- **Era marker:** `metadata.toolTraceVersion = 2` ⇒ v2 (#490) row; absent ⇒ legacy row.
+- Each tool invocation is stored as **two** array elements (a `tool-call` part and
-- Each tool invocation is stored as **two** consecutive array elements — a
+  a `tool-result` part), so naive counting double-counts.
-  `tool-call` part then an OUTCOME part — so naive counting double-counts.
+- **A tool that *throws* writes no result part.** Since the #407 fix its error is
-  - **v2 (#490):** outcome is `{toolName, ok: true}` on success, or
+  persisted as a dedicated `{toolName, error}` element in `tool_calls` (queryable +
-    `{toolName, error, kind: 'thrown'|'interrupted'}` on failure. The tool **OUTPUT
+  replayed to the model). **Rows written before #407 still drop it** — the error is
-    is NOT in `tool_calls`** any more — it lives once in `metadata.parts` (this
+  nowhere in the DB and shows only in the live UI. So `isError` / `success=false`
-    removed a hundreds-of-MB-per-run write duplication). Soft-failure analysis
+  scans under-report by design, and pre-#407 thrown errors are invisible.
-    therefore reads `metadata.parts`, not `tool_calls`.
+- To find where agents fail: (1) soft-failure markers in `tool_calls`, (2) the new
-  - **legacy:** outcome is `{toolName, output}` on success; a **thrown** failure is
+  `error` field for thrown errors (new rows) / the orphan-gap proxy (old rows),
-    a `{toolName, error}` element **only on rows after #407**, and is dropped
+  (3) server logs / the live UI for full stack traces beyond the truncated message.
-    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
 
@@ -69,67 +53,33 @@ 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 — a **call** then an **outcome**.
+two consecutive elements of the `tool_calls` array:
-The outcome shape is era-dependent:
 
 ```text
-# v2 (#490) — metadata.toolTraceVersion = 2
+index 0: { "toolName": "getPage",  "input":  { "pageId": "…" } }   ← tool-call   (has input, NO output)
-index 0: { "toolName":"getPage", "input":{...} }                       ← call     (has input)
+index 1: { "toolName": "getPage",  "output": { … } }                ← tool-result (has output, NO 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 can appear: `toolName`, `input` (call), and on the outcome — **v2:**
+The keys that appear on an element are `toolName`, `input`, `output`, and — for a
-`ok` **or** `error`+`kind`; **legacy:** `output` **or** (post-#407) `error`. There is
+**thrown** failure on rows written after the #407 fix — `error` (the tool's error
-no `state`, no `errorText`, no `type` in `tool_calls` (those live on `metadata.parts`).
+message; see the "Hard failures" section below). There is no `state`, no `errorText`,
-Consequences:
+no `type`. On pre-#407 rows a thrown failure has NO paired result element at all
+(silent orphan). Consequences:
 
-1. **Real invocation count** — count the OUTCOME elements, not every element (else you
+1. **Real invocation count = elements that have `output` or `error`.** Counting every
-   double-count): **v2** = elements with `ok` or `error`; **legacy** = elements with
+   element double-counts (you get ~2× and a spurious "~50% of every tool has no output").
-   `output` or `error`.
+2. **Pairing:** a call = a `tool-call` part followed by its result part. A success
-2. **Pairing:** a call (`input`) is followed by its outcome. `toolName` is on both, so
+   carries `output`; a thrown failure (post-#407) carries `error` instead. Both carry
-   you can group by tool on either. In v2 the `kind` field separates a real hard-fail
+   `toolName`, so you can group by tool on either.
-   (`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 `output` — **on v2 rows in `metadata.parts`** (the
+These are visible in the `tool-result` `output`. The marker differs per tool:
-`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` |
 | --- | --- |
@@ -141,32 +91,37 @@ element's `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 → PERSISTED ✅
+### 2. Hard failures — tool THREW → NOW PERSISTED ✅ (since the #407 fix)
 
 When a tool throws (the classic one is `patchNode` / `insertNode` / `tableUpdateCell`
 → `Failed to encode document to Yjs (fromJSON): Unknown node type: undefined`), the
-runtime writes **no `tool-result` part** — the failure is an ai@6 `tool-error` content
+runtime still writes **no `tool-result` part** — the failure is an ai@6 `tool-error`
-part. How that lands in `tool_calls` depends on the era:
+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).
 
-- **v2 (#490):** a `{toolName, error, kind:'thrown'}` outcome element. An interrupted /
+**Cutover caveat — old rows keep the old blind shape.** Rows written **before** this
-  aborted mid-step call is a **distinct** `{toolName, error:'Tool call did not
+change have the two-part shape (`call` + `output` only) and simply **drop** thrown
-  complete.', kind:'interrupted'}` element — so you can tell a real hard-fail from an
+errors, leaving a silent **orphan** (a `call` with no `output` *and* no `error`). Rows
-  abort **directly, without the orphan heuristic**. Query `kind = 'thrown'`.
+written **after** the fix additionally carry the `error` element. So:
-- **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`).
 
-The same real error text is replayed to the model on the next turn (an `output-error`
+- **New rows:** query the `error` field directly (see the hard-error query below) — no
-part with the real `errorText`, from `metadata.parts`), in every era.
+  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.
 
-**Cutover caveat.** Only pre-#407 legacy rows need the orphan proxy: an orphan is a
+A note on the aborted-call fallback: a call with **neither** a result **nor** a
-`tool-call` with no matching outcome. Orphans there also appear when a run is **aborted**
+`tool-error` (genuinely interrupted mid-step) still replays with the
-mid-flight (server restart), so a high-volume tool (`createComment`, `searchInPage`,
+`'Tool call did not complete.'` placeholder and persists as an orphan — that path is
-`Search_web_search`) shows orphans from aborts, not real errors. Treat the orphan gap as
+unchanged, and is distinct from a real thrown error, which now carries `error`.
-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`
 
@@ -179,34 +134,22 @@ 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** (outcome parts only — the correct denominator).
+**Real invocation count per tool** (result 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'
+WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
-  AND (elem ? 'ok' OR elem ? 'output' OR elem ? 'error')
 GROUP BY 1 ORDER BY 2 DESC;
 ```
 
-**Soft errors per tool.** The soft-error marker lives in the tool OUTPUT — which on
+**Soft errors per tool** (everything the DB can honestly see):
-**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 (m.metadata->>'toolTraceVersion') IS NULL
+  WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
-    AND jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'output'
 )
 SELECT tool, count(*) AS calls,
        sum(COALESCE(
@@ -224,23 +167,13 @@ FROM res GROUP BY tool HAVING sum(COALESCE(
 ORDER BY soft_errors DESC;
 ```
 
-Note the v2 `tool` label is the part type (`tool-editPageText`); strip the `tool-`
+**`editPageText` failure reasons** (the most common real agent mistake — bad `find`):
-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 (m.metadata->>'toolTraceVersion') IS NULL
+  WHERE jsonb_typeof(m.tool_calls) = 'array'
-    AND jsonb_typeof(m.tool_calls) = 'array'
     AND elem->>'toolName' = 'editPageText' AND elem ? 'output'
 )
 SELECT f->>'reason' AS reason, count(*)
@@ -249,43 +182,30 @@ WHERE jsonb_typeof(o->'failed') = 'array'
 GROUP BY 1 ORDER BY 2 DESC;
 ```
 
-**Hard errors — persisted `error` field per tool (v2 + post-#407 rows)** — thrown tool
+**Hard errors — persisted `error` field per tool (NEW rows, since #407)** — thrown
-failures carry their real reason, so query them directly. On **v2** rows exclude the
+tool failures now carry their real reason, so query them directly:
-`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 outcome parts, plus how many distinct chats the gap is spread across).
+(call parts minus result 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 /
+This covers rows written before thrown errors were persisted; on new rows a thrown
-`kind` directly — use the queries above). The `WHERE` restricts to the legacy era so v2
+failure now has its own `error` element (use the query above) and an orphan means only
-rows (where an `ok` outcome is not an `output`) never produce phantom orphans:
+a genuinely aborted mid-step call:
 
 ```sql
 WITH parts AS (
   SELECT m.chat_id, elem->>'toolName' AS tool,
-         (elem ? 'input' AND NOT (elem ? 'output') AND NOT (elem ? 'ok')) AS is_call,
+         (elem ? 'input' AND NOT (elem ? 'output')) AS is_call,
-         (elem ? 'output' OR elem ? 'error' OR elem ? 'ok')               AS is_result
+         (elem ? 'output' OR elem ? 'error')        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
@@ -341,21 +261,11 @@ WHERE tsv @@ websearch_to_tsquery('english', 'some phrase') LIMIT 20;
 
 ## Don't blow up your context
 
-Tool outputs embed full page content and search payloads (hundreds of KB per row).
+A single `tool_calls` row can be **300–400 KB** (results embed full page content and
-On **legacy** rows they are in `tool_calls`; on **v2** rows they moved to
+search payloads). Never `SELECT tool_calls` (or `jsonb_pretty(tool_calls)`) raw.
-`metadata->'parts'` (the `tool_calls` trace itself is now small). Never `SELECT
+Always project just the keys you need and truncate:
-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
@@ -370,32 +280,26 @@ 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**. Thrown-tool error text is **persisted** — in the
+and **wiped on container recreate**. Since the #407 fix, thrown-tool error text is
-`error` field of `tool_calls` (v2 `kind:'thrown'` / post-#407 legacy) — so you no longer
+**persisted in the `error` field** of `tool_calls` (see the hard-error query above), so
-depend on live logs for it. Logs/live UI remain useful for **pre-#407 rows** (whose
+you no longer depend on live logs for it. Logs/live UI remain useful for **pre-#407
-thrown errors were dropped) and for full stack traces beyond the truncated stored
+rows** (whose thrown errors were dropped) and for full stack traces beyond the
-message. A per-tool `tool_calls_total{tool,status}` metric to VictoriaMetrics is still a
+truncated stored message. A per-tool `tool_calls_total{tool,status}` metric to
-possible future add for aggregate dashboards.
+VictoriaMetrics is still a possible future add for aggregate dashboards.
 
 ## Gotchas checklist
 
-- [ ] **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 `output` elements; add `error` elements for thrown failures (new rows), but don't count both as invocations.
-- [ ] 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 a separate `error` element (new rows) or dropped entirely (pre-#407 rows).
-- [ ] `isError` / `success=false` ≈ 0 does **not** mean "no errors" — thrown errors are an `error` element (v2 `kind:'thrown'` / post-#407), not in the output.
+- [ ] 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.
-- [ ] **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` **or** `metadata.parts` cell — outputs are hundreds of KB.
+- [ ] Never dump a raw `tool_calls` cell — it can be hundreds of KB.
-- [ ] Logs are ephemeral (≤50 MB, wiped on recreate) — grab pre-#407 hard-error text live.
+- [ ] Logs are ephemeral (≤50 MB, wiped on recreate) — grab 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,39 +59,6 @@ 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).
@@ -688,32 +655,27 @@ export function CommentsMixin<TBase extends GConstructor<DocmostClientContext>>(
       parentPageId,
     );
 
-    // 2. Fetch comments for each page, keep ones created after since. Runs with
+    // 2. Fetch comments for each page, keep ones created after since
-    // bounded concurrency (#490) instead of one-at-a-time — the per-page reads are
+    const results: any[] = [];
-    // independent, so a large working set no longer costs O(N) serial round-trips.
+    for (const page of pagesInScope) {
-    // Order is preserved (mapWithConcurrency keeps input order), so the output is
+      try {
-    // deterministic regardless of which fetch finishes first.
+        // Full feed (incl. resolved): a "new comments since" scan reports all
-    const perPage = await mapWithConcurrency(
+        // recent activity; the active-only filter is scoped to listComments.
-      pagesInScope,
+        const comments = (await this.listComments(page.id, true)).items;
-      COMMENT_SCAN_CONCURRENCY,
+        const newComments = comments.filter(
-      async (page: any) => {
+          (c: any) => new Date(c.createdAt) > sinceDate,
-        try {
+        );
-          // Full feed (incl. resolved): a "new comments since" scan reports all
+        if (newComments.length > 0) {
-          // recent activity; the active-only filter is scoped to listComments.
+          results.push({
-          const comments = (await this.listComments(page.id, true)).items;
+            pageId: page.id,
-          const newComments = comments.filter(
+            pageTitle: page.title,
-            (c: any) => new Date(c.createdAt) > sinceDate,
+            comments: newComments,
-          );
+          });
-          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,71 +442,3 @@ 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",
-  );
-});

packages/token-estimate/package.json

@@ -1,19 +0,0 @@
-{
-  "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

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

@@ -1,35 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-{
-  "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,9 +287,6 @@ 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)
@@ -564,9 +561,6 @@ 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
@@ -1154,15 +1148,6 @@ 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':