fix(mcp): drawio — авто-стрип XML-комментариев вместо lint-ошибки (#505)

Модель органически вставляет `<!-- ... -->` в mxGraph-XML вопреки запрету
в описании тула (природа LLM, промптингом не лечится). Жёсткая ошибка
линтера [no-comments] заставляла её ПОЛНОСТЬЮ перегенерировать диаграмму —
впустую потраченный tool-call на почти каждой первой генерации.

Теперь в общем prepare-пути (`prepareModel`, через который идут
drawioCreate/drawioUpdate/drawioEditCells) комментарии срезаются ДО линта:
`xml.replace(/<!--[\s\S]*?-->/g, "")`. Комментарии не несут семантики, так
что стрип всегда безопасен. Число срезанных комментариев уходит в
`warnings[]` как `stripped N XML comment(s)` (только при N > 0) — модель это
видит, но НЕ ретраит.

Стрип ГЕЙТИТСЯ на well-formedness: сначала парсим модель, и режем
комментарии только если XML корректен. На malformed-входе (например сырой
неэкранированный `<!--` внутри значения атрибута на пути create/update, где
normalizeInput отдаёт строку без парсинга) стрип НЕ выполняется — иначе он
молча вырезал бы текст автора и принял битую диаграмму. Вместо этого правила
линтера value-escaping / well-formed-xml корректно отклоняют такой вход, и
автор видит реальную ошибку. В корректном XML литеральный `<!--` в значении
обязан быть entity-escaped, а CDATA drawio не использует, поэтому после
проверки well-formedness регэксп бьёт только по настоящим comment-нодам.

Правило `no-comments` в линтере оставлено как defense-in-depth backstop.

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

.env.example

@@ -225,11 +225,26 @@ MCP_DOCMOST_PASSWORD=
 
 # Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
 # Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in
-# ~1 min instead of 15. Note it also cuts a legitimately long but byte-silent
-# single tool call (a slow crawl that emits nothing until done) and an SSE
-# transport idling >1 min BETWEEN tool calls. Default 60000 (1 min).
+# ~1 min instead of 15. It cuts a legitimately long but byte-silent single tool
+# call (a slow crawl that emits nothing until done) on the HTTP (streamable)
+# transport, which opens a fresh request per call. The SSE transport — one
+# long-lived body across many calls — is NO LONGER governed by this timeout
+# (as of #489): its idle-BETWEEN-calls window has its own, raised bodyTimeout,
+# AI_MCP_SSE_BODY_TIMEOUT_MS below. Default 60000 (1 min).
 # AI_MCP_STREAM_TIMEOUT_MS=60000
 
+# bodyTimeout (ms) for the EXTERNAL-MCP SSE transport ONLY (#489). The SSE
+# transport holds ONE response body open across many tool calls, so undici's
+# bodyTimeout (time between body bytes) counts the LEGITIMATE silence BETWEEN the
+# model's tool calls, not just a hung single call. At the tight 1-min silence
+# timeout above, a normal >1-min gap between calls would break the SSE socket and
+# the cache would serve a dead client until TTL — so the SSE transport gets its
+# OWN, RAISED bodyTimeout. A single stuck call is still bounded by the per-call
+# cap (AI_MCP_CALL_TIMEOUT_MS), and a socket that does break is healed by the
+# in-run transport-error retry. The HTTP (streamable) transport keeps the tight
+# timeout. Default 600000 (10 min).
+# AI_MCP_SSE_BODY_TIMEOUT_MS=600000
+
 # Total wall-clock cap (ms) for ONE external MCP tool call (app-level, not
 # transport). Aborts a tool that keeps the socket warm (SSE heartbeats / trickle)
 # but never returns a result — which the silence timeout above never breaks.
@@ -287,6 +302,16 @@ MCP_DOCMOST_PASSWORD=
 # enabled for a workspace, and the same single-instance constraint applies (the
 # registry is process-local).
 # AI_CHAT_RESUMABLE_STREAM=false
+#
+# Per-run replay ring cap (#491), in BYTES, for the resumable-stream registry
+# above. The registry buffers the run's recent SSE tail so a reopened tab can
+# attach and continue from the step it already persisted; the ring is bounded and
+# rotates on every confirmed step-persist. This caps the un-persisted tail between
+# rotations — an overflow evicts the oldest frames and a late attach falls back to
+# 204 -> degraded poll, so correctness never depends on the size. Default 4194304
+# (4MB); a 0/invalid value falls back to the default. The per-subscriber backpressure
+# cap is derived as 2x this value. Only meaningful with AI_CHAT_RESUMABLE_STREAM on.
+# AI_CHAT_RUN_STREAM_MAX_BUFFER_BYTES=4194304
 
 # --- Run lifecycle tunables (#487) ---
 # These govern the universal run machinery (every turn is now a first-class run,

.github/workflows/develop.yml

@@ -62,6 +62,38 @@ jobs:
     needs: [test, e2e-server, e2e-mcp, build]
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    # Image boot-smoke (issue #476): every other job tests code from the working
+    # tree, but the :develop IMAGE that watchtower pulls was never actually
+    # started anywhere (incident classes #353/#452/#361-boot: startup-migrator
+    # crash-loop, runtime module missing from the image, wrong static-asset
+    # headers). The services below back a smoke boot of the exact image right
+    # before it is pushed; a smoke failure blocks the push.
+    services:
+      postgres:
+        # via mirror.gcr.io (Docker Hub pull-through cache; avoids Hub anonymous
+        # pull rate-limit that randomly fails on shared GitHub runner IPs).
+        image: mirror.gcr.io/pgvector/pgvector:pg18
+        env:
+          POSTGRES_DB: docmost
+          POSTGRES_USER: docmost
+          POSTGRES_PASSWORD: docmost
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U docmost"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+      redis:
+        # via mirror.gcr.io (see postgres note above).
+        image: mirror.gcr.io/library/redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -82,6 +114,37 @@ jobs:
         id: version
         run: echo "value=$(git describe --tags --always)" >> "$GITHUB_OUTPUT"
 
+      # Load the image into the local docker daemon so it can be booted (the
+      # push step below exports straight to the registry and leaves nothing
+      # runnable locally). CONVENTION: build-args here must stay TEXTUALLY
+      # IDENTICAL to the push step's build-args — same cache scope + same args
+      # means the layers are reused and the image we smoke IS the image we push.
+      - name: Build image for smoke (load, no push)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          build-args: |
+            APP_VERSION=${{ steps.version.outputs.value }}
+            AI_AGENT_ROLES_CATALOG_URL=https://raw.githubusercontent.com/vvzvlad/gitmost/develop/agent-roles-catalog
+          load: true
+          push: false
+          tags: gitmost:smoke
+          cache-from: type=gha,scope=develop-amd64
+
+      # Boot-smoke the exact image against the job services (see the comment on
+      # `services:` above): health (startup migrator), auth/setup, client dist
+      # served, immutable + brotli asset headers. Fails the job (and therefore
+      # the push) on any miss.
+      - name: Smoke the built image
+        run: bash scripts/ci/image-smoke.sh gitmost:smoke
+
+      # The smoke script leaves the container running on failure precisely so
+      # the boot error (migration mismatch, stack trace) is diagnosable here.
+      - name: Dump smoke container log on failure
+        if: failure()
+        run: docker logs gitmost-smoke 2>&1 | tail -200 || true
+
       - name: Build and push develop image
         uses: docker/build-push-action@v6
         with:

.github/workflows/nightly-property.yml

@@ -124,9 +124,17 @@ jobs:
           exit "$FAILED"
 
       # A GENUINE counterexample: fast-check printed a shrunk minimal case and its
-      # reproducing seed into property-output.txt. File a dedup-guarded issue whose
-      # title prefix is UNIQUE to counterexamples, so an infra failure (handled by
-      # the next step under a different title) can never poison this dedup.
+      # reproducing seed into property-output.txt. File a dedup-guarded issue.
+      #
+      # Dedup is keyed on a HASH of the SHRUNK COUNTEREXAMPLE (the minimal failing
+      # input), NOT on the issue title prefix. Keying on the prefix would let a
+      # single open issue swallow every OTHER counterexample (a different bug B whose
+      # title shares the prefix would be treated as a duplicate and stay silent until
+      # the first issue is closed). Hashing the shrunk example instead means two
+      # DIFFERENT counterexamples get two DIFFERENT issues, while a re-find of the
+      # SAME counterexample still dedupes onto the existing one. The infra-failure
+      # step (below) still keys on its own distinct title, so it can never poison
+      # this dedup either.
       - name: File counterexample issue
         # always() is REQUIRED: the fuzz step exits nonzero on a failing shard,
         # so a bare `if:` (implicitly success() && ...) would skip this step
@@ -146,25 +154,48 @@ jobs:
             echo "No fast-check counterexample signature — infra failure, handled by the next step."
             exit 0
           fi
-          TITLE="${TITLE_PREFIX} (seed=${FAIL_SEED})"
+          # Extract the SHRUNK counterexample block: the "Counterexample:" line(s)
+          # up to (but excluding) the "Shrunk N time(s)" / "Got error" line. This is
+          # the minimal failing INPUT and is STABLE across the different seeds/paths
+          # that reach the same bug — unlike the seed, path, or shrink count (which
+          # precede/follow this block and vary run-to-run) and unlike the whole
+          # output (which embeds those varying parts). Hashing THIS is what makes the
+          # dedup identity the bug itself rather than an incidental run detail.
+          CE_TEXT=$(awk '/Counterexample:/{c=1} /Shrunk [0-9]+ time|Got error/{c=0} c{print}' property-output.txt)
+          if [ -z "$CE_TEXT" ]; then
+            # No parseable shrunk block (unexpected — the signature check above
+            # already confirmed fast-check output). Fall back to the reproducing
+            # seed so we still emit a stable identity instead of silently deduping.
+            CE_TEXT="seed:${FAIL_SEED}"
+          fi
+          # Stable short id: first 12 hex chars of sha256 over the counterexample.
+          CE_HASH=$(printf '%s' "$CE_TEXT" | sha256sum | cut -c1-12)
+          # Machine-readable marker embedded in the issue body; the open-issue search
+          # below matches on it (and on the hash in the title) so identity travels
+          # with the issue regardless of any human title edits.
+          CE_MARKER="<!-- counterexample-hash: ${CE_HASH} -->"
+          export CE_HASH CE_MARKER
+          TITLE="${TITLE_PREFIX} [${CE_HASH}] (seed=${FAIL_SEED})"
 
-          # Best-effort dedup: skip if an open issue with the counterexample title
-          # prefix already exists. A failure of this check must NOT block creation.
+          # Dedup on the counterexample hash: skip only if an OPEN issue already
+          # carries this exact hash (in its title or its body marker). A different
+          # counterexample has a different hash and is NOT deduped. A failure of this
+          # check must NOT block creation.
           EXISTING=""
           if EXISTING=$(curl -sS \
               -H "Authorization: token ${GITHUB_TOKEN}" \
               "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/issues?state=open&limit=100"); then
             if printf '%s' "$EXISTING" \
-                | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let a;try{a=JSON.parse(s)}catch{process.exit(1)}if(!Array.isArray(a))process.exit(1);const p=process.env.TITLE_PREFIX;process.exit(a.some(i=>typeof i.title==="string"&&i.title.startsWith(p))?0:1)})'; then
-              echo "An open '${TITLE_PREFIX}' issue already exists — skipping creation."
+                | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let a;try{a=JSON.parse(s)}catch{process.exit(1)}if(!Array.isArray(a))process.exit(1);const h=process.env.CE_HASH,m=process.env.CE_MARKER;process.exit(a.some(i=>(typeof i.title==="string"&&i.title.includes(h))||(typeof i.body==="string"&&i.body.includes(m)))?0:1)})'; then
+              echo "An open issue for counterexample ${CE_HASH} already exists — skipping creation."
               exit 0
             fi
           fi
 
           # Build the JSON body with the test output SAFELY escaped (never hand-
           # interpolate the counterexample into JSON).
-          BODY_TEXT=$(printf 'A nightly property fuzz SHARD failed with a fast-check counterexample.\n\n- failing shard seed: `%s`\n- NUM_RUNS (per shard): `%s`\n- run: %s\n\nReproduce locally:\n\n```\nPROPERTY_SEED=%s PROPERTY_NUM_RUNS=%s pnpm --filter @docmost/prosemirror-markdown exec vitest run test/generative/\n```\n\nfast-check shrinks the failure to a minimal counterexample. Commit it as a permanent fixture under `packages/prosemirror-markdown/test/fixtures/counterexamples/` + a case in `counterexamples.test.ts`, then FIX the converter (do not weaken a property). See `packages/prosemirror-markdown/README.md`.\n\nTail of the test output (contains the shrunk counterexample):\n\n```\n%s\n```\n' \
-            "$FAIL_SEED" "$NUM_RUNS" "$RUN_URL" "$FAIL_SEED" "$NUM_RUNS" "$(tail -n 120 property-output.txt)")
+          BODY_TEXT=$(printf 'A nightly property fuzz SHARD failed with a fast-check counterexample.\n\n- counterexample hash: `%s`\n- failing shard seed: `%s`\n- NUM_RUNS (per shard): `%s`\n- run: %s\n\nReproduce locally:\n\n```\nPROPERTY_SEED=%s PROPERTY_NUM_RUNS=%s pnpm --filter @docmost/prosemirror-markdown exec vitest run test/generative/\n```\n\nfast-check shrinks the failure to a minimal counterexample. Commit it as a permanent fixture under `packages/prosemirror-markdown/test/fixtures/counterexamples/` + a case in `counterexamples.test.ts`, then FIX the converter (do not weaken a property). See `packages/prosemirror-markdown/README.md`.\n\nTail of the test output (contains the shrunk counterexample):\n\n```\n%s\n```\n\n%s\n' \
+            "$CE_HASH" "$FAIL_SEED" "$NUM_RUNS" "$RUN_URL" "$FAIL_SEED" "$NUM_RUNS" "$(tail -n 120 property-output.txt)" "$CE_MARKER")
 
           jq -n --arg title "$TITLE" --arg body "$BODY_TEXT" \
             '{title: $title, body: $body}' > payload.json

.github/workflows/test.yml

@@ -25,37 +25,65 @@ jobs:
   # filename sorts BEFORE migrations already applied on the target branch (and
   # thus in prod). The Kysely startup migrator rejects that as "corrupted
   # migrations" and crash-loops the app on boot (incident #361). This gate fails
-  # the PR so the migration is renamed to a current timestamp before merge. Only
-  # runs for pull_request events (needs a base branch to diff against).
+  # the PR so the migration is renamed to a current timestamp before merge.
+  # Runs for pull_request (diff against the base branch) AND for push (#476
+  # retrospective: a DIRECT push to develop used to bypass this PR-only gate
+  # entirely — now the push is diffed against its `before` SHA; workflow_call
+  # from develop.yml inherits the caller's push event). workflow_dispatch has
+  # nothing to diff against and still skips the job.
   migration-order:
-    if: github.event_name == 'pull_request'
+    if: github.event_name == 'pull_request' || github.event_name == 'push'
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - name: Checkout (full history for the base-branch diff)
+      - name: Checkout (full history for the base diff)
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Added migrations must sort after the newest on the base branch
+      - name: Added migrations must sort after the newest on the base
         env:
           TARGET_BRANCH: ${{ github.base_ref }}
+          BEFORE_SHA: ${{ github.event.before }}
         run: |
           set -euo pipefail
           MIG_DIR="apps/server/src/database/migrations"
-          # checkout above already did fetch-depth:0 (full history). Fetch the base
-          # WITHOUT --depth (a shallow graft would truncate the base history and
-          # break the merge-base when the base has moved ahead of the PR merge —
-          # exactly the long-branch-vs-moving-base case this gate guards, #361).
-          git fetch --no-tags origin "$TARGET_BRANCH"
-          newest_on_target=$(git ls-tree -r --name-only "origin/${TARGET_BRANCH}" "$MIG_DIR" | sort | tail -1)
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request" ]; then
+            # checkout above already did fetch-depth:0 (full history). Fetch the base
+            # WITHOUT --depth (a shallow graft would truncate the base history and
+            # break the merge-base when the base has moved ahead of the PR merge —
+            # exactly the long-branch-vs-moving-base case this gate guards, #361).
+            git fetch --no-tags origin "$TARGET_BRANCH"
+            BASE="origin/${TARGET_BRANCH}"
+          else
+            # push event: compare against the pre-push tip of the branch.
+            if [ "$BEFORE_SHA" = "0000000000000000000000000000000000000000" ]; then
+              echo "::notice::branch creation push — nothing to compare"
+              exit 0
+            fi
+            if ! git cat-file -e "${BEFORE_SHA}^{commit}" 2>/dev/null; then
+              # The before-SHA is not in the clone (a force-push rewrote history).
+              # One recovery attempt — refresh every remote head (cheap: the
+              # checkout is already fetch-depth:0); a fetch failure aborts via
+              # `set -e`, which is fail-closed too.
+              git fetch --no-tags origin '+refs/heads/*:refs/remotes/origin/*'
+            fi
+            if ! git cat-file -e "${BEFORE_SHA}^{commit}" 2>/dev/null; then
+              # FAIL-CLOSED: without the before-SHA there is no base to prove the
+              # ordering against, and a gate whose job is to BLOCK must not guess.
+              echo "::error::force-push detected — verify migration order manually, then re-run via workflow_dispatch"
+              exit 1
+            fi
+            BASE="$BEFORE_SHA"
+          fi
+          newest_on_target=$(git ls-tree -r --name-only "$BASE" "$MIG_DIR" | sort | tail -1)
           # NO `|| true`: a diff failure (e.g. an unresolved merge-base) must fail
           # the job CLOSED — a gate whose job is to BLOCK must never pass on error.
           # `set -e` above already aborts on a non-zero diff exit.
-          added=$(git diff --diff-filter=A --name-only "origin/${TARGET_BRANCH}...HEAD" -- "$MIG_DIR")
+          added=$(git diff --diff-filter=A --name-only "${BASE}...HEAD" -- "$MIG_DIR")
           bad=0
           for f in $added; do
             if [[ "$f" < "$newest_on_target" || "$f" == "$newest_on_target" ]]; then
-              echo "::error::Migration $f sorts at or before the newest on ${TARGET_BRANCH} ($newest_on_target) — rename it with a CURRENT timestamp before merge (do not change its contents). See incident #361."
+              echo "::error::Migration $f sorts at or before the newest on the base ($newest_on_target) — rename it with a CURRENT timestamp before merge (do not change its contents). See incident #361."
               bad=1
             fi
           done

.gitignore

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

AGENTS.md

@@ -471,6 +471,8 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
 - Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`, `ai`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons. The `ai@6.0.134` patch carries TWO independent server fixes, each with its own tripwire test: (1) it disables the SDK's O(n²) cumulative `partialOutput` accumulation when no output strategy is requested (server heap OOM on long agent runs, #184; tripwire: `apps/server/src/integrations/ai/ai-sdk-partial-output.patch.spec.ts`); (2) it fixes `writeToServerResponse`'s drain-hang — the loop awaited only `"drain"` under backpressure, so a mid-write client disconnect parked the pipe forever and leaked the reader/buffers until restart; it now races `"drain"` against `"close"`/`"error"`, cancels the reader on disconnect, and swallows the fire-and-forget read rejection (#486; tripwire: `apps/server/src/integrations/ai/ai-sdk-drain-hang.patch.spec.ts`). Both tripwires assert BOTH installed dist builds carry their patch marker. The patch MUST be re-created via `pnpm patch` when bumping `ai`.
+  - **Upstream tracking (report the analysis upstream, don't just carry it):** both `ai` fixes and the hocuspocus one are candidates for upstreaming so we can eventually drop the local patch — the analysis is already written up in each patch's `PATCH(...)` header comments. File (a) an upstream **issue** on `vercel/ai` for the O(n²) cumulative `partialOutput` accumulation (heap OOM), (b) an upstream **issue** on `vercel/ai` for the `writeToServerResponse` drain-hang, and (c) an upstream **PR** on `@hocuspocus/server` for the connect-vs-unload race (local marker `PATCH(gitmost #401)` in `patches/@hocuspocus__server@3.4.4.patch`). Do NOT edit the patch files to add links — the patch bytes feed `patch_hash` in `pnpm-lock.yaml` (`ai@6.0.134` → `e8c599b3…`), so any content change there desyncs the lockfile pin and breaks `pnpm install`; keep upstream references here instead.
+  - **`ai` version is split across the monorepo and MUST be aligned deliberately, NOT casually:** the server pins `ai@6.0.134` (patched, exact — the `patchedDependencies` key forces that version), while the client declares `ai@6.0.207` (unpatched — the server-side `writeToServerResponse`/`partialOutput` fixes are dead code in the browser, so the mismatch is currently benign but is real drift). Alignment is a **planned, install-gated step**, never a bare `package.json` edit: (1) choose the target version; (2) re-create ALL THREE patch hunks (partialOutput publish-each, the `DefaultStreamTextResult` lazy-`output` wiring, and the drain-hang race) against the target dist via `pnpm patch` — the line offsets shift between versions, so the current patch WILL fail to apply as-is; (3) run a full `pnpm install` so the lockfile + new `patch_hash` regenerate together; (4) confirm both tripwire specs still find their markers. `pnpm install` FAILS HARD on an unapplied patch — that failure is the guardrail, so treat the port as a deliberate plan rather than discovering it as a deploy-time surprise.
 - **The MCP tool inventory in `SERVER_INSTRUCTIONS` is GENERATED from the registry** (`packages/mcp/src/server-instructions.ts`: `buildToolInventory()` over `SHARED_TOOL_SPECS`) and spliced into the hand-written routing prose (`ROUTING_PROSE`). So adding/renaming/removing a **shared** spec in `packages/mcp/src/tool-specs.ts` auto-updates the `<tool_inventory>` — no manual `SERVER_INSTRUCTIONS` edit needed. Only an **inline** MCP-only tool (those registered via `server.registerTool(...)` in `index.ts`, not through the registry) needs a one-line entry in `INLINE_MCP_INVENTORY`. Enforced by `packages/mcp/test/unit/tool-inventory.test.mjs`, which fails when a registered tool is missing from the generated inventory (there is no `EXCEPTIONS` opt-out anymore — every tool must appear). Update `ROUTING_PROSE` when a tool's *intent guidance* (when-to-use) changes. `packages/mcp/build/` is gitignored and rebuilt in CI/Docker via `pnpm build` (same convention as `git-sync`/`prosemirror-markdown`) — never commit it; rebuild locally after editing to run the tests.
 
 ## CI / release

CHANGELOG.md

@@ -129,6 +129,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **A drifted comment suggestion can be re-synced instead of failing forever
+  with a 409.** A suggestion whose stored anchor no longer matched the live
+  document used to reject every apply attempt with an unrecoverable conflict; a
+  new resync path re-reads the live anchor so the suggestion applies against the
+  current text, and orphaned anchors (whose marked run was deleted) are
+  reconciled rather than left blocking. (#496)
+- **Save intentional page versions.** Press `Cmd/Ctrl+S` (or use the page menu)
+  to save a named version of a page. The history panel now distinguishes
+  intentional versions (a "Saved" / "Agent version" badge) from automatic
+  snapshots, dims autosaves, and offers an "Only versions" filter. Automatic
+  snapshots switched from a fixed interval to a trailing idle-flush with a
+  max-wait ceiling, and a boundary snapshot is pinned whenever the editing source
+  changes (e.g. a person's edits followed by the AI agent). (#370)
+
 - **Place several images side by side in a row.** A new "Inline (side by
   side)" alignment mode in the image bubble menu renders consecutive inline
   images as a row that wraps onto the next line on narrow screens. The row is
@@ -304,6 +318,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   longer controls whether a turn is a run — it now governs **only** the
   browser-disconnect semantics (ON = detached/survives a disconnect; OFF = a
   disconnect stops the run). (#487)
+- **Vendor `ai` patch: upstream-tracking + version-alignment plan documented.**
+  The two local `ai@6.0.134` fixes (O(n²) `partialOutput` heap-OOM; the
+  `writeToServerResponse` drain-hang) and the hocuspocus connect-vs-unload race
+  now have explicit upstream-reporting and `ai`-version-alignment steps recorded
+  in `AGENTS.md` (client `ai@6.0.207` vs server `ai@6.0.134`-patched drift). The
+  patch bytes are unchanged — they feed the lockfile `patch_hash`, so the
+  alignment is called out as an install-gated plan rather than a bare version
+  bump. No runtime change.
 - **Client markdown paste/copy and AI-chat rendering now go through the canonical
   converter.** Pasting markdown into the editor, "Copy as markdown", the AI title
   generator, and the AI-chat markdown renderer all now use
@@ -336,6 +358,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **MCP write tools no longer report a false failure that provokes a duplicate
+  write.** `drawioCreate` used to throw when the diagram landed as a NESTED block
+  (anchored inside a callout or table cell) because there is no `#<index>` handle
+  for it — but the diagram was already written, so a retry-prone agent re-created
+  it and produced a duplicate. It now returns success with `nodeId: null` plus a
+  warning that explains the write landed and how to re-read it (via
+  `getOutline` / `getPageJson` by `attachmentId`). Separately, when the live
+  collaboration-session cache hits its LRU entry cap, evicting a session whose
+  write is still in flight no longer rejects that write as a hard failure — it is
+  reported as INDETERMINATE ("the update may already have persisted; verify
+  before retry") so the agent re-reads instead of blind-retrying, and a
+  still-connecting session is no longer picked as an idle eviction victim by a
+  parallel acquire. (#494)
+- **A long AI chat no longer bricks on the model's context window, and each turn
+  stops re-persisting the whole tool-output history.** Tool outputs are now
+  stored ONCE, in `metadata.parts`; the `tool_calls` trace keeps only per-step
+  outcome flags (a v2 trace shape), ending the O(N²) write amplification that
+  re-wrote every prior output on every step (measured on a live Postgres via the
+  `pg_current_wal_lsn()` delta: the trace column shrank ~3200×, the full
+  assistant row ~51%). The persisted record is unchanged in content — the full
+  history still lives in `metadata.parts`. At REPLAY time only, the history sent
+  to the provider is now bounded by a deterministic, prompt-cache-friendly token
+  budget: `floor(0.7 × chatContextWindow)` when a window is configured (no cap —
+  anti-brick protection, not a cost limiter), a flat 100k fallback for installs
+  with no window set (exactly the ones that hit terminal overflow), or off when
+  the window is explicitly `0`. Trimming truncates old tool outputs first, then
+  mechanically collapses the oldest turns, always keeping the recent turns full
+  and the tool-call/result pairing balanced. A provider context-overflow 400 is
+  now classified and used as a reactive signal: the row is stamped so the NEXT
+  turn re-trims aggressively (0.5×), which un-bricks a chat that just 400'd. The
+  client token badge and the server budgeter now share one estimator (new
+  `@docmost/token-estimate` package) so they can never diverge. Deferred-tool
+  activation is also cached in the chat metadata to avoid re-resolving it each
+  turn. (#490)
+- **A chat with one malformed message part no longer 500s on every turn, and a
+  failed send no longer duplicates the user's message.** Incoming client parts
+  are now whitelisted to `text` (a forged tool-result part can no longer reach
+  the persisted history or the model context), and the turn is converted BEFORE
+  the user row is inserted, so a mid-flight failure cannot leave a duplicate
+  user row that a retry then compounds. A single part that still fails to convert
+  degrades to a `[tool context omitted]` marker on that one row instead of
+  bricking the whole chat. (#489)
+- **A transport drop to an external MCP server now heals within the same turn.**
+  On an undici transport error, a read-only MCP tool reconnects its server and
+  retries once within the run; a write is never auto-retried (it may already have
+  applied). One flapping server no longer nulls the shared client cache, so other
+  servers' cached clients are untouched. The SSE transport also gets a raised
+  body-timeout so a legitimate >1-min idle between the model's tool calls no
+  longer breaks a long-lived SSE socket (new `AI_MCP_SSE_BODY_TIMEOUT_MS`, default
+  10 min; see `.env.example`). (#489)
+- **Decisions on comment suggestions now leave a durable audit record.**
+  Applying or dismissing a comment suggestion hard-deletes the (childless)
+  subject comment, so the only surviving trace of who decided what is the audit
+  event — but the audit trail was wired to a Noop service that silently
+  swallowed every event. The trail is now DB-backed, so
+  `comment.suggestion_applied` / `comment.suggestion_dismissed` (and the other
+  comment-decision events) persist to the `audit` table and can be reviewed
+  after the comment is gone. A persistence failure is still swallowed with a
+  warning so it never breaks the originating request. (#496)
+- **Applying a comment suggestion no longer strips the replaced run's inline
+  formatting.** The suggested text was re-inserted carrying only the comment
+  anchor mark, silently dropping bold/italic/code/link on the affected run; the
+  prevailing formatting of the replaced run is now carried onto the applied
+  text. (#496)
+- **Markdown round-trips no longer silently drop a line that opens with a block
+  trigger.** When a document is exported to Markdown and re-imported (git-sync
+  stabilize, agent writes), a paragraph or continuation line (after a hard break)
+  that begins with a block marker — an ATX heading `#`, a blockquote/callout `>`,
+  a list marker (`-`/`*`/`+`/`N.`/`N)`), a code fence, a table `|`, a thematic
+  break (`---`), or a setext underline (`--`, `----`, or a lone `=`) — is now
+  backslash-escaped so it round-trips as text instead of being re-parsed into a
+  heading/list/quote/rule and losing its content. Front-matter stripping is
+  scoped to the import path only. (#493)
 - **The server no longer runs out of heap during long autonomous agent runs.** A
   new pnpm patch on `ai@6.0.134` stops the SDK from building a cumulative
   snapshot of the ENTIRE turn text on every streamed text-delta when no output
@@ -452,6 +547,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   through that exact share (its own share or an ancestor `includeSubPages`
   share); any other value now returns the generic "not found" instead of
   serving the page. (#218)
+- **MCP tool-allowlist semantics flipped: an empty `[]` now means deny-all
+  (previously it was coerced to "no restrictions").** For an external MCP server,
+  a stored `tool_allowlist` of `[]` now denies **every** tool of that server
+  (zero tools reach the agent) instead of being treated as an empty/unset filter
+  that allowed all of them. A corrupt or non-array stored value now **fails
+  closed** to deny-all rather than silently allowing everything. The admin form
+  no longer silently widens an existing deny-all server: leaving its tag field
+  empty preserves `[]` (deny-all) on save instead of NULL-ing the column to
+  allow-all, so a routine rename/toggle can no longer grant the agent every tool.
+  "No restrictions" is still expressible — a genuinely unrestricted server stores
+  NULL, and clearing the field on such a server keeps it NULL. Operationally
+  significant: audit any server that was created or left with a literal `[]`, as
+  it now exposes no tools until an explicit allowlist (or NULL) is set. (#476)
 
 - **Tool and provider error text no longer leaks to anonymous readers in the
   public-share AI chat.** A failing tool's raw error (which could carry an

README.md

@@ -206,6 +206,137 @@ start the new migrations apply on top of your existing schema (`CREATE EXTENSION
   existing pages are indexed on their next edit. pgvector is still required for the migration to
   apply at all.
 
+## Local embeddings server
+
+The AI agent's semantic (RAG) search needs an **embeddings model**. Instead of paying a cloud
+provider (e.g. OpenAI `text-embedding-3-*`) to embed every page, you can run a small open-weights
+model yourself with Hugging Face
+[Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference) (TEI), which
+serves an OpenAI-compatible `/v1/embeddings` endpoint. `intfloat/multilingual-e5-small` is a good
+default: multilingual, 384-dim, and comfortable on CPU (~1–2 GB RAM, 1–2 vCPU). Point Gitmost at it
+under **Workspace settings → AI → Embeddings**.
+
+### Option A — local (same Docker network as Gitmost)
+
+Run TEI as a container on the network Gitmost is already on. The port is never published, so the
+endpoint stays internal and needs no authentication.
+
+```yaml
+services:
+  embeddings:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9   # pin version; use a cuda-* tag for GPU
+    container_name: embeddings
+    restart: unless-stopped
+    networks:
+      - gitmost_net          # same network Gitmost is on
+    command:
+      - "--model-id"
+      - "intfloat/multilingual-e5-small"
+      - "--auto-truncate"    # clamp over-long inputs instead of returning 413
+    volumes:
+      - tei-models:/data     # weights are downloaded once and cached here
+
+networks:
+  gitmost_net:
+    external: true           # the network Gitmost already uses
+
+volumes:
+  tei-models:
+```
+
+Gitmost settings (**Workspace settings → AI → Embeddings**):
+
+| Field             | Value                             |
+|-------------------|-----------------------------------|
+| Model             | `intfloat/multilingual-e5-small`  |
+| Base URL          | `http://embeddings:80/v1/`        |
+| Embedding API key | — (leave empty)                   |
+
+> `embeddings` is the container name — Gitmost resolves it over DNS inside the Docker network.
+> The port is not published, so the endpoint is reachable only by containers on that network and
+> no authorization is required.
+
+### Option B — separate host (public via Traefik + Let's Encrypt)
+
+This assumes the host already runs Traefik with an ACME resolver (the example below uses
+`letsEncrypt`, the `websecure` entrypoint and a shared `docker_main_net` network). Replace the
+domain / network / resolver with your own.
+
+**DNS:** add an A record `embeddings.example.com` → the IP of your Traefik host (same
+challenge / port 80 as the rest of your sites).
+
+```yaml
+services:
+  embeddings:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9   # pin version; cuda-* tag for GPU
+    container_name: embeddings
+    restart: unless-stopped
+    networks:
+      - docker_main_net      # the network Traefik is attached to
+    command:
+      - "--model-id"
+      - "intfloat/multilingual-e5-small"
+      - "--auto-truncate"
+      - "--api-key"
+      - "sk-emb-REPLACE_WITH_YOUR_KEY"
+    volumes:
+      - tei-models:/data
+    labels:
+      traefik.enable: "true"
+      traefik.http.routers.embeddings.rule: "Host(`embeddings.example.com`)"
+      traefik.http.routers.embeddings.entrypoints: "websecure"
+      traefik.http.routers.embeddings.tls: "true"
+      traefik.http.routers.embeddings.tls.certresolver: "letsEncrypt"
+      traefik.http.routers.embeddings.service: "embeddings"
+      traefik.http.services.embeddings.loadbalancer.server.port: "80"
+      # TEI enforces the Bearer key itself; Traefik only rate-limits to protect the CPU
+      traefik.http.routers.embeddings.middlewares: "embeddings-rl"
+      traefik.http.middlewares.embeddings-rl.ratelimit.average: "20"
+      traefik.http.middlewares.embeddings-rl.ratelimit.burst: "40"
+      traefik.http.middlewares.embeddings-rl.ratelimit.period: "1s"
+
+networks:
+  docker_main_net:
+    external: true
+
+volumes:
+  tei-models:
+```
+
+Gitmost settings (**Workspace settings → AI → Embeddings**):
+
+| Field             | Value                                 |
+|-------------------|---------------------------------------|
+| Model             | `intfloat/multilingual-e5-small`      |
+| Base URL          | `https://embeddings.example.com/v1/`  |
+| Embedding API key | your `sk-emb-…`                       |
+
+Check it from outside:
+
+```bash
+curl -s https://embeddings.example.com/v1/embeddings \
+  -H "Authorization: Bearer sk-emb-REPLACE_WITH_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"intfloat/multilingual-e5-small","input":"query: hello"}' \
+  | python3 -c 'import sys,json;print("dims:",len(json.load(sys.stdin)["data"][0]["embedding"]))'
+# -> dims: 384
+```
+
+### Embeddings server notes
+
+- **Vector dimension is 384.** If this Gitmost was previously embedded with a different model
+  (e.g. `text-embedding-3-large` = 3072-dim), the old pgvector rows won't match the new dimension —
+  clear the existing embeddings / re-index before switching. Gitmost only compares vectors of the
+  same dimension, so mixed-dimension rows are silently ignored rather than searched.
+- **First start downloads the weights** (hundreds of MB) from `huggingface.co` into the
+  `tei-models` volume; every start after that reads from the volume.
+- **Pin the version.** Pin the image, and optionally the model: add `--revision <commit-sha>` to
+  `command` (the sha is on the model's page on Hugging Face).
+- **Air-gapped / no egress:** seed the `tei-models` volume ahead of time and add
+  `environment: [HF_HUB_OFFLINE=1]`.
+- **GPU:** use the cuda tag of the same release (e.g.
+  `ghcr.io/huggingface/text-embeddings-inference:cuda-1.9`) and start the container with `gpus: all`.
+
 ## Features
 
 - Real-time collaboration

README.ru.md

@@ -193,6 +193,137 @@ dump/restore, существующий каталог данных переис
 > неизменным и бэкапьте вместе с базой данных.
 
 
+## Локальный сервер эмбеддингов
+
+Семантическому (RAG) поиску AI-агента нужна **модель эмбеддингов**. Вместо оплаты облачного
+провайдера (например, OpenAI `text-embedding-3-*`) за эмбеддинг каждой страницы можно запустить
+небольшую open-weights модель у себя через Hugging Face
+[Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference) (TEI) — он
+отдаёт OpenAI-совместимый эндпоинт `/v1/embeddings`. Хороший дефолт — `intfloat/multilingual-e5-small`:
+многоязычная, 384-мерная, комфортно работает на CPU (~1–2 ГБ RAM, 1–2 vCPU). Пропишите её в
+**Настройки воркспейса → AI → Эмбеддинги**.
+
+### Вариант A — локально (та же Docker-сеть, что и Gitmost)
+
+Запустите TEI контейнером в той же сети, где уже работает Gitmost. Порт наружу не публикуется,
+поэтому эндпоинт остаётся внутренним и не требует авторизации.
+
+```yaml
+services:
+  embeddings:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9   # pin version; use a cuda-* tag for GPU
+    container_name: embeddings
+    restart: unless-stopped
+    networks:
+      - gitmost_net          # same network Gitmost is on
+    command:
+      - "--model-id"
+      - "intfloat/multilingual-e5-small"
+      - "--auto-truncate"    # clamp over-long inputs instead of returning 413
+    volumes:
+      - tei-models:/data     # weights are downloaded once and cached here
+
+networks:
+  gitmost_net:
+    external: true           # the network Gitmost already uses
+
+volumes:
+  tei-models:
+```
+
+Настройки Gitmost (**Настройки воркспейса → AI → Эмбеддинги**):
+
+| Поле              | Значение                          |
+|-------------------|-----------------------------------|
+| Model             | `intfloat/multilingual-e5-small`  |
+| Base URL          | `http://embeddings:80/v1/`        |
+| Embedding API key | — (оставить пустым)               |
+
+> `embeddings` — имя контейнера, Gitmost резолвит его по DNS внутри Docker-сети.
+> Наружу порт не публикуется, эндпоинт доступен только контейнерам этой сети, поэтому
+> авторизация не нужна.
+
+### Вариант B — на отдельном хосте (наружу через Traefik + Let's Encrypt)
+
+Предполагается, что на хосте уже есть Traefik с ACME-резолвером (в примере ниже — `letsEncrypt`,
+entrypoint `websecure`, общая сеть `docker_main_net`). Замените домен / сеть / резолвер на свои.
+
+**DNS:** заведите A-запись `embeddings.example.com` → IP хоста с Traefik (тот же challenge / порт 80,
+что и у остальных сайтов).
+
+```yaml
+services:
+  embeddings:
+    image: ghcr.io/huggingface/text-embeddings-inference:cpu-1.9   # pin version; cuda-* tag for GPU
+    container_name: embeddings
+    restart: unless-stopped
+    networks:
+      - docker_main_net      # the network Traefik is attached to
+    command:
+      - "--model-id"
+      - "intfloat/multilingual-e5-small"
+      - "--auto-truncate"
+      - "--api-key"
+      - "sk-emb-REPLACE_WITH_YOUR_KEY"
+    volumes:
+      - tei-models:/data
+    labels:
+      traefik.enable: "true"
+      traefik.http.routers.embeddings.rule: "Host(`embeddings.example.com`)"
+      traefik.http.routers.embeddings.entrypoints: "websecure"
+      traefik.http.routers.embeddings.tls: "true"
+      traefik.http.routers.embeddings.tls.certresolver: "letsEncrypt"
+      traefik.http.routers.embeddings.service: "embeddings"
+      traefik.http.services.embeddings.loadbalancer.server.port: "80"
+      # TEI enforces the Bearer key itself; Traefik only rate-limits to protect the CPU
+      traefik.http.routers.embeddings.middlewares: "embeddings-rl"
+      traefik.http.middlewares.embeddings-rl.ratelimit.average: "20"
+      traefik.http.middlewares.embeddings-rl.ratelimit.burst: "40"
+      traefik.http.middlewares.embeddings-rl.ratelimit.period: "1s"
+
+networks:
+  docker_main_net:
+    external: true
+
+volumes:
+  tei-models:
+```
+
+Настройки Gitmost (**Настройки воркспейса → AI → Эмбеддинги**):
+
+| Поле              | Значение                              |
+|-------------------|---------------------------------------|
+| Model             | `intfloat/multilingual-e5-small`      |
+| Base URL          | `https://embeddings.example.com/v1/`  |
+| Embedding API key | ваш `sk-emb-…`                        |
+
+Проверка снаружи:
+
+```bash
+curl -s https://embeddings.example.com/v1/embeddings \
+  -H "Authorization: Bearer sk-emb-REPLACE_WITH_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"intfloat/multilingual-e5-small","input":"query: hello"}' \
+  | python3 -c 'import sys,json;print("dims:",len(json.load(sys.stdin)["data"][0]["embedding"]))'
+# -> dims: 384
+```
+
+### Заметки про сервер эмбеддингов
+
+- **Размерность вектора — 384.** Если раньше этот Gitmost эмбеддился другой моделью
+  (например, `text-embedding-3-large` = 3072-dim), старые строки в pgvector не совпадут по
+  размерности — очистите существующие эмбеддинги / переиндексируйте перед переключением. Gitmost
+  сравнивает только вектора одной размерности, поэтому строки другой размерности не участвуют в
+  поиске, а не ломают его.
+- **Первый старт тянет веса** (сотни МБ) с `huggingface.co` в том `tei-models`; дальше — из тома.
+- **Пин версии.** Пиньте образ, а при желании и модель: добавьте в `command` `--revision <commit-sha>`
+  (sha берётся со страницы модели на Hugging Face).
+- **Без egress (air-gapped):** засейте том `tei-models` заранее и добавьте
+  `environment: [HF_HUB_OFFLINE=1]`.
+- **GPU:** возьмите cuda-тег того же релиза (например,
+  `ghcr.io/huggingface/text-embeddings-inference:cuda-1.9`) и запустите контейнер с `gpus: all`.
+
+
 ## Возможности
 
 - Совместная работа в реальном времени

apps/client/package.json

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

apps/client/public/locales/en-US/translation.json

@@ -1418,5 +1418,14 @@
   "The commented text changed since this suggestion was made; it was not applied.": "The commented text changed since this suggestion was made; it was not applied.",
   "Dismiss": "Dismiss",
   "Suggestion dismissed": "Suggestion dismissed",
-  "Failed to dismiss suggestion": "Failed to dismiss suggestion"
+  "Failed to dismiss suggestion": "Failed to dismiss suggestion",
+  "Save version": "Save version",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Version saved",
+  "Already saved as the latest version": "Already saved as the latest version",
+  "Agent version": "Agent version",
+  "Boundary": "Boundary",
+  "Autosave": "Autosave",
+  "Only versions": "Only versions",
+  "No saved versions yet.": "No saved versions yet."
 }

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

@@ -256,6 +256,9 @@
   "Invite link": "Ссылка для приглашения",
   "Copy": "Копировать",
   "Copy to space": "Копировать в пространство",
+  "Copy chat": "Копировать чат",
+  "Dock to sidebar": "Закрепить в боковой панели",
+  "Undock": "Открепить",
   "Copied": "Скопировано",
   "Failed to export chat": "Не удалось экспортировать чат",
   "Duplicate": "Дублировать",
@@ -285,6 +288,9 @@
   "Alt text": "Альтернативный текст",
   "Describe this for accessibility.": "Опишите это для специальных возможностей.",
   "Add a description": "Добавить описание",
+  "Caption": "Подпись",
+  "Add a caption": "Добавить подпись",
+  "Shown below the image.": "Отображается под изображением.",
   "Justify": "По ширине",
   "Merge cells": "Объединить ячейки",
   "Split cell": "Разделить ячейку",
@@ -388,22 +394,6 @@
   "Quote": "Цитата",
   "Image": "Изображение",
   "Audio": "Аудио",
-  "Transcribe": "Транскрибировать",
-  "Transcribing…": "Транскрибация…",
-  "No speech detected": "Речь не распознана",
-  "Transcription failed": "Не удалось распознать речь",
-  "Voice dictation is not configured": "Голосовой ввод не настроен",
-  "Start dictation": "Начать диктовку",
-  "Stop recording": "Остановить запись",
-  "Microphone access denied": "Доступ к микрофону запрещён",
-  "No microphone found": "Микрофон не найден",
-  "Microphone is unavailable or already in use": "Микрофон недоступен или уже используется",
-  "Could not start recording": "Не удалось начать запись",
-  "Audio recording is not available in this browser/context": "Запись аудио недоступна в этом браузере/контексте",
-  "Dictation": "Диктовка",
-  "Dictation becomes available once the page finishes connecting": "Диктовка станет доступна после подключения к документу",
-  "No connection to the collaboration server — dictation unavailable": "Нет связи с сервером совместного редактирования — диктовка недоступна",
-  "This page is read-only": "Страница открыта только для чтения",
   "Embed PDF": "Встроить PDF",
   "Upload and embed a PDF file.": "Загрузите и встроите PDF-файл.",
   "Embed as PDF": "Встроить как PDF",
@@ -419,9 +409,6 @@
   "Footnote {{number}}": "Сноска {{number}}",
   "Go to footnote": "Перейти к сноске",
   "Back to reference": "Вернуться к ссылке",
-  "Back to references": "Вернуться к ссылкам",
-  "Back to reference {{label}}": "Вернуться к ссылке {{label}}",
-  "Empty footnote": "Пустая сноска",
   "Math inline": "Строчная формула",
   "Insert inline math equation.": "Вставить математическое выражение в строку.",
   "Math block": "Блок формулы",
@@ -447,6 +434,9 @@
   "{{count}} command available_other": "Доступно {{count}} команд",
   "{{count}} result available_one": "Доступен 1 результат",
   "{{count}} result available_other": "Доступно {{count}} результатов",
+  "{{count}} result found_one": "Найден {{count}} результат",
+  "{{count}} result found_few": "Найдено {{count}} результата",
+  "{{count}} result found_other": "Найдено {{count}} результатов",
   "Equal columns": "Равные столбцы",
   "Left sidebar": "Левая боковая панель",
   "Right sidebar": "Правая боковая панель",
@@ -456,6 +446,7 @@
   "Names do not match": "Названия не совпадают",
   "Today, {{time}}": "Сегодня, {{time}}",
   "Yesterday, {{time}}": "Вчера, {{time}}",
+  "now": "сейчас",
   "Space created successfully": "Пространство успешно создано",
   "Space updated successfully": "Пространство успешно обновлено",
   "Space deleted successfully": "Пространство успешно удалено",
@@ -559,6 +550,7 @@
   "Add 2FA method": "Добавить метод 2FA",
   "Backup codes": "Резервные коды",
   "Disable": "Отключить",
+  "disabled": "отключено",
   "Invalid verification code": "Недействительный код подтверждения",
   "New backup codes have been generated": "Новые резервные коды сгенерированы",
   "Failed to regenerate backup codes": "Не удалось заново сгенерировать резервные коды",
@@ -702,62 +694,6 @@
   "AI search": "Поиск ИИ",
   "AI Answer": "Ответ ИИ",
   "Ask AI": "Спросить ИИ",
-  "AI agent": "AI-агент",
-  "Take a look at the current document": "Посмотри текущий документ",
-  "Start automatically": "Запускать автоматически",
-  "When on, picking this role sends a launch message and starts the chat. When off, the role is selected and you type the first message yourself.": "Когда включено, выбор этой роли отправляет стартовое сообщение и начинает чат. Когда выключено, роль выбирается, а первое сообщение вы вводите сами.",
-  "Launch message": "Стартовое сообщение",
-  "Sent automatically when this role is picked. Leave empty to use the default text. Ignored when “Start automatically” is off.": "Отправляется автоматически при выборе этой роли. Оставьте пустым, чтобы использовать текст по умолчанию. Игнорируется, когда «Запускать автоматически» выключено.",
-  "AI agent is typing…": "AI-агент печатает…",
-  "{{name}} is typing…": "{{name}} печатает…",
-  "Thinking…": "Думаю…",
-  "Thinking… · {{count}} tokens": "Думаю… · {{count}} токенов",
-  "Thinking… · {{count}} tokens_one": "Думаю… · {{count}} токен",
-  "Thinking… · {{count}} tokens_few": "Думаю… · {{count}} токена",
-  "Thinking… · {{count}} tokens_many": "Думаю… · {{count}} токенов",
-  "Thinking · {{count}} tokens": "Размышления · {{count}} токенов",
-  "Thinking · {{count}} tokens_one": "Размышления · {{count}} токен",
-  "Thinking · {{count}} tokens_few": "Размышления · {{count}} токена",
-  "Thinking · {{count}} tokens_many": "Размышления · {{count}} токенов",
-  "Agent role": "Роль агента",
-  "AI chat": "AI-чат",
-  "AI chat is disabled for this workspace.": "AI-чат отключён для этого рабочего пространства.",
-  "Ask a question about this documentation.": "Задайте вопрос об этой документации.",
-  "Ask a question…": "Задайте вопрос…",
-  "Ask the AI agent anything about your workspace.": "Спросите AI-агента о чём угодно по вашему рабочему пространству.",
-  "Ask the AI agent…": "Спросите AI-агента…",
-  "Copy chat": "Копировать чат",
-  "Dock to sidebar": "Закрепить в боковой панели",
-  "Undock": "Открепить",
-  "Created successfully": "Успешно создано",
-  "Context size / model limit": "Размер контекста / лимит модели",
-  "Context window (tokens)": "Окно контекста (токены)",
-  "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
-  "Delete this chat?": "Удалить этот чат?",
-  "Deleted successfully": "Успешно удалено",
-  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
-  "AI agent {{name}}": "AI-агент {{name}}",
-  "Failed to delete chat": "Не удалось удалить чат",
-  "Failed to rename chat": "Не удалось переименовать чат",
-  "Failed": "Ошибка",
-  "OK · {{n}}": "OK · {{n}}",
-  "Test": "Тест",
-  "No tools available": "Инструменты недоступны",
-  "Available tools": "Доступные инструменты",
-  "Minimize": "Свернуть",
-  "No chats yet.": "Чатов пока нет.",
-  "Send": "Отправить",
-  "Send when the agent finishes": "Отправить, когда агент закончит",
-  "Queue message": "Поставить в очередь",
-  "Remove queued message": "Убрать из очереди",
-  "Send now": "Отправить сейчас",
-  "Interrupt and send now": "Прервать и отправить сейчас",
-  "Something went wrong": "Что-то пошло не так",
-  "Stop": "Стоп",
-  "The AI agent could not respond. Please try again.": "AI-агент не смог ответить. Попробуйте ещё раз.",
-  "The AI provider is not configured. Ask an administrator to set it up.": "AI-провайдер не настроен. Попросите администратора настроить его.",
-  "Universal assistant": "Универсальный ассистент",
-  "You": "Вы",
   "AI is thinking...": "ИИ обрабатывает запрос...",
   "Thinking": "Думаю",
   "Ask a question...": "Задайте вопрос...",
@@ -784,8 +720,40 @@
   "Manage API keys for all users in the workspace. View the <anchor>API documentation</anchor> for usage details.": "Управляйте API-ключами для всех пользователей в рабочем пространстве. Смотрите <anchor>документацию по API</anchor> для получения информации об использовании.",
   "View the <anchor>API documentation</anchor> for usage details.": "Смотрите <anchor>документацию по API</anchor> для получения информации об использовании.",
   "View the <anchor>MCP documentation</anchor>.": "Смотрите <anchor>документацию по MCP</anchor>.",
-  "Instructions": "Инструкции",
+  "AI / Models": "ИИ / Модели",
+  "AI / External tools (MCP)": "ИИ / Внешние инструменты (MCP)",
+  "Add server": "Добавить сервер",
+  "Edit server": "Изменить сервер",
+  "Delete server": "Удалить сервер",
+  "Are you sure you want to delete this MCP server?": "Вы уверены, что хотите удалить этот MCP-сервер?",
+  "No external servers configured": "Внешние серверы не настроены",
+  "Server name": "Имя сервера",
+  "Transport": "Транспорт",
+  "URL": "URL",
+  "Authorization header": "Заголовок авторизации",
+  "Tool allowlist": "Список разрешённых инструментов",
+  "Optional. Leave empty to allow all tools the server exposes.": "Необязательно. Оставьте пустым, чтобы разрешить все инструменты, которые предоставляет сервер.",
   "Optional guidance for the agent on how and when to use this server's tools. Injected into the system prompt. The server's tools are namespaced as \"<server name>_*\".": "Необязательное указание агенту, как и когда использовать инструменты этого сервера. Добавляется в системный промпт. Инструменты сервера именуются с префиксом «<имя сервера>_*».",
+  "Test": "Тест",
+  "Available tools": "Доступные инструменты",
+  "No tools available": "Инструменты недоступны",
+  "Failed": "Ошибка",
+  "OK · {{n}}": "OK · {{n}}",
+  "Created successfully": "Успешно создано",
+  "Deleted successfully": "Успешно удалено",
+  "Clear": "Очистить",
+  "Provider": "Провайдер",
+  "•••• set": "•••• задан",
+  "Clear key": "Очистить ключ",
+  "Base URL": "Базовый URL",
+  "Chat model": "Модель чата",
+  "Embedding model": "Модель эмбеддингов",
+  "System message": "Системное сообщение",
+  "A built-in safety framework is always appended.": "Встроенный набор правил безопасности всегда добавляется автоматически.",
+  "Test connection": "Проверить соединение",
+  "Connection successful": "Соединение установлено",
+  "Connection failed": "Не удалось установить соединение",
+  "Only workspace admins can manage AI provider settings.": "Управлять настройками провайдера ИИ могут только администраторы рабочего пространства.",
   "Sources": "Источники",
   "AI Answers not available for attachments": "Ответы ИИ недоступны для вложений",
   "No answer available": "Ответ недоступен",
@@ -1013,6 +981,7 @@
   "Try again": "Попробовать снова",
   "Untitled chat": "Чат без названия",
   "No document": "Без документа",
+  "You": "Вы",
   "What can I help you with?": "Чем я могу вам помочь?",
   "Are you sure you want to revoke this {{credential}}": "Вы уверены, что хотите отозвать этот {{credential}}",
   "Automatically provision users and groups from your identity provider via SCIM.": "Автоматически предоставляйте доступ пользователям и группам из вашего провайдера удостоверений через SCIM.",
@@ -1041,6 +1010,9 @@
   "Page menu": "Меню страницы",
   "Expand": "Развернуть",
   "Collapse": "Свернуть",
+  "Expand all": "Развернуть все",
+  "Collapse all": "Свернуть все",
+  "Couldn't expand the tree: {{reason}}": "Не удалось развернуть дерево: {{reason}}",
   "Comment menu": "Меню комментария",
   "Group menu": "Меню группы",
   "Show hidden breadcrumbs": "Показать скрытые хлебные крошки",
@@ -1077,7 +1049,7 @@
   "Search pages and spaces...": "Поиск страниц и пространств...",
   "No results found": "Результаты не найдены",
   "You don't have permission to create pages here": "У вас нет прав на создание страниц здесь",
-  "Chat menu": "Меню чата",
+  "Chat menu for {{title}}": "Меню чата для {{title}}",
   "API key menu": "Меню API-ключа",
   "Jump to comment selection": "Перейти к выбору комментария",
   "Slash commands": "Команды со слешем",
@@ -1131,6 +1103,9 @@
   "Undo": "Отменить",
   "Redo": "Повторить",
   "Backlinks": "Обратные ссылки",
+  "Back to references": "Вернуться к ссылкам",
+  "Back to reference {{label}}": "Вернуться к ссылке {{label}}",
+  "Empty footnote": "Пустая сноска",
   "Last updated by": "Последний изменивший",
   "Last updated": "Последнее обновление",
   "Stats": "Статистика",
@@ -1164,6 +1139,7 @@
   "Page title": "Заголовок страницы",
   "Page content": "Содержимое страницы",
   "Member actions": "Действия с участником",
+  "Member actions for {{name}}": "Действия с участником {{name}}",
   "Toggle password visibility": "Переключить видимость пароля",
   "Send comment": "Отправить комментарий",
   "Token actions": "Действия с токеном",
@@ -1183,11 +1159,187 @@
   "Removed from favorites": "Удалено из избранного",
   "Added {{name}} to favorites": "{{name}} добавлено в избранное",
   "Removed {{name}} from favorites": "{{name}} удалено из избранного",
+  "Label added": "Метка добавлена",
+  "Label removed": "Метка удалена",
+  "Image updated": "Изображение обновлено",
+  "Unsupported image type": "Неподдерживаемый тип изображения",
+  "Member deactivated": "Участник деактивирован",
+  "Member activated": "Участник активирован",
+  "Name is required": "Укажите имя",
+  "Name must be 40 characters or fewer": "Имя должно содержать не более 40 символов",
+  "Group name must be at least 2 characters": "Название группы должно содержать не менее 2 символов",
+  "Group name must be 100 characters or fewer": "Название группы должно содержать не более 100 символов",
+  "Description must be 500 characters or fewer": "Описание должно содержать не более 500 символов",
+  "Invalid invitation link": "Недействительная ссылка-приглашение",
   "Page menu for {{name}}": "Меню страницы для {{name}}",
   "Create subpage of {{name}}": "Создать подстраницу для {{name}}",
+  "AI chat": "AI-чат",
+  "Ask a question about this documentation.": "Задайте вопрос об этой документации.",
+  "Ask a question…": "Задайте вопрос…",
+  "Thinking…": "Думаю…",
+  "Thinking… · {{count}} tokens": "Думаю… · {{count}} токенов",
+  "Thinking… · {{count}} tokens_one": "Думаю… · {{count}} токен",
+  "Thinking… · {{count}} tokens_few": "Думаю… · {{count}} токена",
+  "Thinking… · {{count}} tokens_many": "Думаю… · {{count}} токенов",
+  "Thinking… · {{count}} tokens_other": "Думаю… · {{count}} токенов",
+  "Thinking · {{count}} tokens": "Размышления · {{count}} токенов",
+  "Thinking · {{count}} tokens_one": "Размышления · {{count}} токен",
+  "Thinking · {{count}} tokens_few": "Размышления · {{count}} токена",
+  "Thinking · {{count}} tokens_many": "Размышления · {{count}} токенов",
+  "Thinking · {{count}} tokens_other": "Размышления · {{count}} токенов",
+  "The assistant is unavailable right now. Please try again.": "Ассистент сейчас недоступен. Попробуйте ещё раз.",
+  "Public share assistant": "Ассистент публичного доступа",
+  "Let anonymous visitors of public shares ask an AI assistant scoped to that share's pages. You pay for the tokens.": "Позвольте анонимным посетителям публичных ссылок обращаться к ИИ-ассистенту в рамках страниц этой публикации. Токены оплачиваете вы.",
+  "Public assistant model": "Модель публичного ассистента",
+  "Defaults to the chat model": "По умолчанию используется модель чата",
+  "Optional cheaper model id for the public assistant. Empty uses the chat model above.": "Необязательный более дешёвый идентификатор модели для публичного ассистента. Если пусто, используется модель чата выше.",
+  "Assistant identity": "Личность ассистента",
+  "Pick an agent role whose persona the public assistant adopts. The safety rules always still apply.": "Выберите роль агента, чью личность примет публичный ассистент. Правила безопасности всегда остаются в силе.",
+  "Built-in assistant persona": "Встроенная личность ассистента",
+  "Minimize": "Свернуть",
+  "Context size / model limit": "Размер контекста / лимит модели",
+  "Context window (tokens)": "Окно контекста (токены)",
+  "Shown as used / total in the chat header. Leave empty to hide the limit.": "Показывается в шапке чата как использовано / всего. Пусто — лимит скрыт.",
+  "AI agent": "AI-агент",
+  "Take a look at the current document": "Посмотри текущий документ",
+  "AI agent is typing…": "AI-агент печатает…",
+  "{{name}} is typing…": "{{name}} печатает…",
+  "Send": "Отправить",
+  "Send when the agent finishes": "Отправить, когда агент закончит",
+  "Queue message": "Поставить в очередь",
+  "Remove queued message": "Убрать из очереди",
+  "Send now": "Отправить сейчас",
+  "Interrupt and send now": "Прервать и отправить сейчас",
+  "Stop": "Стоп",
+  "Response stopped.": "Ответ остановлен.",
+  "Connection lost — the answer was interrupted.": "Соединение потеряно — ответ был прерван.",
+  "Response stopped (manually or the connection dropped).": "Ответ остановлен (вручную или из-за разрыва соединения).",
+  "Chat menu": "Меню чата",
+  "No chats yet.": "Чатов пока нет.",
+  "Delete this chat?": "Удалить этот чат?",
+  "Ask the AI agent…": "Спросите AI-агента…",
+  "Ask the AI agent anything about your workspace.": "Спросите AI-агента о чём угодно по вашему рабочему пространству.",
+  "Failed to rename chat": "Не удалось переименовать чат",
+  "Failed to delete chat": "Не удалось удалить чат",
+  "Something went wrong": "Что-то пошло не так",
+  "AI chat is disabled for this workspace.": "AI-чат отключён для этого рабочего пространства.",
+  "The AI provider is not configured. Ask an administrator to set it up.": "AI-провайдер не настроен. Попросите администратора настроить его.",
+  "The AI agent could not respond. Please try again.": "AI-агент не смог ответить. Попробуйте ещё раз.",
+  "Searched pages": "Поиск по страницам",
+  "Read page": "Прочитана страница",
+  "Created page": "Создана страница",
+  "Updated page": "Обновлена страница",
+  "Renamed page": "Переименована страница",
+  "Moved page": "Перемещена страница",
+  "Deleted page (to trash)": "Удалена страница (в корзину)",
+  "Commented": "Добавлен комментарий",
+  "Resolved comment": "Комментарий решён",
+  "Ran tool {{name}}": "Выполнен инструмент {{name}}",
+  "AI agent «{{role}}» on behalf of {{person}}": "AI-агент «{{role}}» от имени {{person}}",
+  "AI agent {{name}}": "AI-агент {{name}}",
+  "Endpoints": "Эндпоинты",
+  "where we fetch models": "откуда мы получаем модели",
+  "All endpoints are OpenAI-compatible. Point the Base URL at OpenAI, OpenRouter, a local Ollama, or any self-hosted server.": "Все эндпоинты совместимы с OpenAI. Укажите в базовом URL адрес OpenAI, OpenRouter, локального Ollama или любого self-hosted сервера.",
+  "Chat / LLM": "Чат / LLM",
+  "root": "корневой",
+  "Semantic search": "Семантический поиск",
+  "Voice / STT": "Голос / STT",
+  "Voice dictation": "Голосовой ввод",
+  "Streaming dictation": "Потоковый голосовой ввод",
+  "Transcribe as you speak, cutting on pauses": "Транскрибирование по мере речи, с разбивкой на паузах",
+  "Voice dictation is not available yet.": "Голосовой ввод пока недоступен.",
+  "Test endpoint": "Проверить эндпоинт",
+  "Save and test": "Сохранить и проверить",
+  "Save endpoints": "Сохранить эндпоинты",
+  "Configured and enabled": "Настроено и включено",
+  "Configured but disabled": "Настроено, но отключено",
+  "Enabled but not configured": "Включено, но не настроено",
+  "Not configured": "Не настроено",
+  "External tools": "Внешние инструменты",
+  "Gitmost as MCP client": "Gitmost как MCP-клиент",
+  "Servers the agent calls out to.": "Серверы, к которым обращается агент.",
+  "MCP server": "MCP-сервер",
+  "expose the workspace": "открыть доступ к рабочему пространству",
+  "Enable MCP server": "Включить MCP-сервер",
+  "Exposes the workspace as an MCP server at /mcp — this provides a capability, it doesn't consume a model.": "Открывает рабочее пространство как MCP-сервер по адресу /mcp — это предоставляет возможность, а не потребляет модель.",
+  "Resolves to {{url}}": "Разрешается в {{url}}",
+  "Model": "Модель",
+  "Done": "Готово",
+  "shared prompt · safety framework appended automatically": "общий промпт · правила безопасности добавляются автоматически",
+  "/v1/chat/completions · root endpoint — Embeddings and Voice inherit its URL and key": "/v1/chat/completions · корневой эндпоинт — Эмбеддинги и Голос наследуют его URL и ключ",
+  "/v1/embeddings · embeds pages so semantic search can find them": "/v1/embeddings · создаёт эмбеддинги страниц, чтобы их находил семантический поиск",
+  "/v1/audio/transcriptions · works with local whisper (speaches / faster-whisper-server)": "/v1/audio/transcriptions · работает с локальным whisper (speaches / faster-whisper-server)",
+  "Vector search · requires pgvector": "Векторный поиск · требуется pgvector",
+  "Embedding API key": "API-ключ для эмбеддингов",
+  "Embeddings": "Эмбеддинги",
+  "Leave empty to use the chat API key": "Оставьте пустым, чтобы использовать API-ключ чата",
+  "Leave empty to use the chat base URL": "Оставьте пустым, чтобы использовать базовый URL чата",
+  "Reindex now": "Переиндексировать сейчас",
+  "Start dictation": "Начать диктовку",
+  "Stop recording": "Остановить запись",
+  "Transcribing…": "Транскрибация…",
+  "Microphone access denied": "Доступ к микрофону запрещён",
+  "No microphone found": "Микрофон не найден",
+  "Could not start recording": "Не удалось начать запись",
+  "Transcription failed": "Не удалось распознать речь",
+  "Transcribe": "Транскрибировать",
+  "No speech detected": "Речь не распознана",
+  "Voice dictation is not configured": "Голосовой ввод не настроен",
+  "Microphone is unavailable or already in use": "Микрофон недоступен или уже используется",
+  "Audio recording is not available in this browser/context": "Запись аудио недоступна в этом браузере/контексте",
+  "Dictation": "Диктовка",
+  "Dictation becomes available once the page finishes connecting": "Диктовка станет доступна после подключения к документу",
+  "No connection to the collaboration server — dictation unavailable": "Нет связи с сервером совместного редактирования — диктовка недоступна",
+  "This page is read-only": "Страница открыта только для чтения",
+  "Request format": "Формат запроса",
+  "How transcription requests are sent to the endpoint": "Как запросы на транскрибирование отправляются на эндпоинт",
+  "OpenAI-compatible (multipart/form-data)": "Совместимо с OpenAI (multipart/form-data)",
+  "OpenRouter (JSON, base64 audio)": "OpenRouter (JSON, аудио в base64)",
   "Dictation language": "Язык диктовки",
   "Auto-detect": "Автоопределение",
   "Spoken language hint sent to the transcription model. Auto-detect lets the model decide.": "Подсказка языка речи для модели транскрипции. «Автоопределение» оставляет выбор за моделью.",
+  "Agent role": "Роль агента",
+  "Universal assistant": "Универсальный ассистент",
+  "Add role": "Добавить роль",
+  "Edit role": "Изменить роль",
+  "Role name": "Название роли",
+  "e.g. Proofreader": "напр. Корректор",
+  "Optional. Shown as the chat badge.": "Необязательно. Отображается как значок чата.",
+  "Optional. A short note about what this role does.": "Необязательно. Краткое описание того, что делает эта роль.",
+  "Instructions": "Инструкции",
+  "The built-in safety framework is always added automatically.": "Встроенный набор правил безопасности всегда добавляется автоматически.",
+  "Model provider override": "Переопределение провайдера модели",
+  "Optional. Defaults to the workspace provider.": "Необязательно. По умолчанию используется провайдер рабочего пространства.",
+  "Model override": "Переопределение модели",
+  "Optional. Defaults to the workspace model.": "Необязательно. По умолчанию используется модель рабочего пространства.",
+  "e.g. gpt-4o-mini": "напр. gpt-4o-mini",
+  "If you choose a different provider, it must already be configured in AI settings.": "Если вы выбираете другого провайдера, он уже должен быть настроен в настройках ИИ.",
+  "Start automatically": "Запускать автоматически",
+  "When on, picking this role sends a launch message and starts the chat. When off, the role is selected and you type the first message yourself.": "Когда включено, выбор этой роли отправляет стартовое сообщение и начинает чат. Когда выключено, роль выбирается, а первое сообщение вы вводите сами.",
+  "Launch message": "Стартовое сообщение",
+  "Sent automatically when this role is picked. Leave empty to use the default text. Ignored when “Start automatically” is off.": "Отправляется автоматически при выборе этой роли. Оставьте пустым, чтобы использовать текст по умолчанию. Игнорируется, когда «Запускать автоматически» выключено.",
+  "Agent roles": "Роли агента",
+  "Reusable presets that shape the agent's behavior (and optionally its model). Picked when starting a new chat.": "Многоразовые пресеты, определяющие поведение агента (и, при желании, его модель). Выбираются при запуске нового чата.",
+  "No roles configured": "Роли не настроены",
+  "Delete role": "Удалить роль",
+  "Are you sure you want to delete this role?": "Вы уверены, что хотите удалить эту роль?",
+  "HTML embed": "HTML-вставка",
+  "Edit HTML embed": "Изменить HTML-вставку",
+  "HTML embed is disabled in this workspace": "HTML-вставки отключены в этом рабочем пространстве",
+  "Click to add HTML / CSS / JS": "Нажмите, чтобы добавить HTML / CSS / JS",
+  "This HTML/CSS/JS runs in a sandboxed frame and cannot access the viewer's session, cookies, or API.": "Этот HTML/CSS/JS выполняется в изолированном фрейме и не имеет доступа к сессии, cookie или API просматривающего.",
+  "<script>...</script>": "<script>...</script>",
+  "Height (px, blank = auto)": "Высота (px, пусто = авто)",
+  "advanced": "дополнительно",
+  "Enable HTML embed": "Включить HTML-вставки",
+  "Allow members to insert raw HTML/CSS/JavaScript blocks. The block renders in a sandboxed frame and cannot access the viewer's session, cookies, or API. Off by default.": "Разрешить участникам вставлять блоки с необработанным HTML/CSS/JavaScript. Блок отображается в изолированном фрейме и не имеет доступа к сессии, cookie или API просматривающего. По умолчанию выключено.",
+  "When enabled, any member can insert an HTML embed block. The toggle just enables or disables the block type workspace-wide.": "Когда включено, любой участник может вставить блок HTML-вставки. Переключатель просто включает или отключает этот тип блока во всём рабочем пространстве.",
+  "Embeds run inside a sandboxed iframe with a separate origin, so they cannot read or modify the page they are embedded in.": "Вставки выполняются в изолированном iframe с отдельным источником, поэтому они не могут читать или изменять страницу, в которую встроены.",
+  "Turning this off hides existing embeds (they render as a disabled placeholder) and stops serving them on public share pages.": "Отключение этой опции скрывает существующие вставки (они отображаются как отключённая заглушка) и прекращает их показ на публичных страницах.",
+  "Analytics / tracker": "Аналитика / трекер",
+  "Injected verbatim into the <head> of PUBLIC SHARE pages only (same-origin). For analytics snippets (Google Analytics, Yandex.Metrika, etc.). Admin only.": "Вставляется дословно в <head> только ПУБЛИЧНЫХ страниц (тот же источник). Для сниппетов аналитики (Google Analytics, Яндекс.Метрика и т. п.). Только для администраторов.",
+  "Go to login page": "Перейти на страницу входа",
+  "Move to space": "Переместить в пространство",
   "Float left (wrap text)": "Обтекание слева",
   "Float right (wrap text)": "Обтекание справа",
   "Inline (side by side)": "В ряд",
@@ -1199,6 +1351,7 @@
   "Showing {{count}} subpages_one": "Показано {{count}} подстраница",
   "Showing {{count}} subpages_few": "Показано {{count}} подстраницы",
   "Showing {{count}} subpages_many": "Показано {{count}} подстраниц",
+  "Showing {{count}} subpages_other": "Показано {{count}} подстраниц",
   "Protocol": "Протокол",
   "How chat requests are sent and how reasoning is surfaced": "Как отправляются запросы чата и как показывается reasoning",
   "OpenAI-compatible (surfaces reasoning)": "OpenAI-совместимый (показывает reasoning)",
@@ -1268,7 +1421,6 @@
   "Retry": "Повторить",
   "The catalog is empty": "Каталог пуст",
   "No role bundles are published for this language yet. Try switching the content language.": "Для этого языка ещё не опубликовано ни одного набора ролей. Попробуйте сменить язык контента.",
-  "No roles configured": "Роли не настроены",
   "Already up to date": "Уже актуальна",
   "Updated to the latest version": "Обновлено до последней версии",
   "This role is no longer in the catalog": "Эта роль больше не представлена в каталоге",
@@ -1281,5 +1433,14 @@
   "The commented text changed since this suggestion was made; it was not applied.": "Прокомментированный текст изменился после создания предложения; оно не было применено.",
   "Dismiss": "Не применять",
   "Suggestion dismissed": "Предложение отклонено",
-  "Failed to dismiss suggestion": "Не удалось отклонить предложение"
+  "Failed to dismiss suggestion": "Не удалось отклонить предложение",
+  "Save version": "Сохранить версию",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Версия сохранена",
+  "Already saved as the latest version": "Уже сохранено как последняя версия",
+  "Agent version": "Версия агента",
+  "Boundary": "Граница",
+  "Autosave": "Автосейв",
+  "Only versions": "Только версии",
+  "No saved versions yet.": "Пока нет сохранённых версий."
 }

apps/client/src/components/chunk-load-error-boundary.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isChunkLoadError } from "./chunk-load-error-boundary";
+import { isChunkLoadError, shouldAutoReload } from "./chunk-load-error-boundary";
 
 // The detector decides whether a caught render error is a stale-deploy chunk-404
 // (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
@@ -35,3 +35,31 @@ describe("isChunkLoadError", () => {
     expect(isChunkLoadError(err)).toBe(false);
   });
 });
+
+// The window gate replaces the old one-shot flag: it must permit recovery across
+// several deploys in one tab (each > window apart) while still stopping an infinite
+// reload loop when a lazy chunk is permanently broken (a second failure < window).
+describe("shouldAutoReload", () => {
+  const WINDOW = 5 * 60 * 1000;
+  const NOW = 1_000_000_000_000;
+
+  it("allows a reload when we have never auto-reloaded", () => {
+    expect(shouldAutoReload(NOW, null, WINDOW)).toBe(true);
+  });
+
+  it("allows a reload when the last one was 6 minutes ago (outside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 6 * 60 * 1000, WINDOW)).toBe(true);
+  });
+
+  it("blocks a reload when the last one was 1 minute ago (inside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 1 * 60 * 1000, WINDOW)).toBe(false);
+  });
+
+  it("blocks a reload exactly at the window boundary (not strictly older)", () => {
+    expect(shouldAutoReload(NOW, NOW - WINDOW, WINDOW)).toBe(false);
+  });
+
+  it("allows a reload when the stored timestamp is unparseable (NaN)", () => {
+    expect(shouldAutoReload(NOW, NaN, WINDOW)).toBe(true);
+  });
+});

apps/client/src/components/chunk-load-error-boundary.tsx

@@ -2,7 +2,25 @@ import { ReactNode } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { Button, Center, Stack, Text } from "@mantine/core";
 
-const RELOAD_FLAG = "chunk-reload-attempted";
+// sessionStorage key holding the epoch-ms timestamp of the last automatic reload.
+const RELOAD_AT_KEY = "chunk-reload-at";
+// Allow at most one automatic reload per this window. A stale-deploy 404 is cured
+// by a single reload, so anything inside the window is treated as a reload loop
+// (permanently-broken chunk) and falls through to the manual UI. A window (rather
+// than a one-shot flag) lets a SECOND deploy in the same tab's lifetime recover too.
+const RELOAD_WINDOW_MS = 5 * 60 * 1000;
+
+// Pure window decision, unit-tested in isolation: auto-reload only if we have never
+// auto-reloaded (lastReloadAt null/NaN) or the last one was strictly older than the
+// window. Anything inside the window is suppressed to break an infinite reload loop.
+export function shouldAutoReload(
+  now: number,
+  lastReloadAt: number | null,
+  windowMs: number,
+): boolean {
+  if (lastReloadAt === null || Number.isNaN(lastReloadAt)) return true;
+  return now - lastReloadAt > windowMs;
+}
 
 // Heuristic detection of a failed dynamic import. Since the code-splitting work,
 // every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
@@ -24,12 +42,16 @@ export function isChunkLoadError(error: unknown): boolean {
 function handleError(error: unknown) {
   if (!isChunkLoadError(error)) return;
   // A stale-chunk 404 is cured by a full reload that re-fetches index.html and
-  // the new chunk manifest. Auto-reload once, guarding against a reload loop
-  // (e.g. a genuinely missing chunk) with a one-shot sessionStorage flag. If the
-  // flag is already set we fall through to the manual recovery UI below.
+  // the new chunk manifest. Auto-reload at most once per RELOAD_WINDOW_MS: this
+  // recovers across multiple deploys in a single tab's lifetime, yet a
+  // permanently-broken lazy chunk (which would loop) is stopped after the first
+  // reload and falls through to the manual recovery UI below.
   try {
-    if (sessionStorage.getItem(RELOAD_FLAG)) return;
-    sessionStorage.setItem(RELOAD_FLAG, "1");
+    const raw = sessionStorage.getItem(RELOAD_AT_KEY);
+    const lastReloadAt = raw === null ? null : Number.parseInt(raw, 10);
+    const now = Date.now();
+    if (!shouldAutoReload(now, lastReloadAt, RELOAD_WINDOW_MS)) return;
+    sessionStorage.setItem(RELOAD_AT_KEY, String(now));
   } catch {
     // sessionStorage unavailable (private mode / disabled): skip the automatic
     // reload rather than risk an unguarded loop; the fallback UI still recovers.

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

@@ -58,8 +58,11 @@ import ConversationList from "@/features/ai-chat/components/conversation-list.ts
 import ChatThread from "@/features/ai-chat/components/chat-thread.tsx";
 import {
   exportAiChat,
+  getAiChatMessagesDelta,
   stopRun,
 } from "@/features/ai-chat/services/ai-chat-service.ts";
+import { mergeDeltaRowsIntoPages } from "@/features/ai-chat/utils/resume-helpers.ts";
+import type { IAiChatMessageRow } from "@/features/ai-chat/types/ai-chat.types.ts";
 import { useChatSession } from "@/features/ai-chat/hooks/use-chat-session.ts";
 import {
   shouldCollapseOnOutsidePointer,
@@ -86,19 +89,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
-// armed when a resume attempt could not attach to the live run and disarmed by the
-// thread on settle / local stream; this cap is the ONLY backstop against an endless
-// tick (a stuck 'streaming' row before the boot-sweep, or a user-tail 204 with no
-// run).
-//
-// #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;
+// #184 phase 1.5 / #430 / #488: the degraded-poll fallback. The window owns only
+// a DUMB 2.5s timer, gated by an armed flag; the THREAD's run-lifecycle FSM owns
+// arm/disarm AND the inactivity cap that turns a stuck run into a `stalled` banner
+// (#488 commit 4a — the cap moved into the thread so polling->stalled is a single
+// FSM transition; the window no longer silently stops polling at the cap).
 
 /** Compact token formatter: 1.2M / 3.4k / 950. */
 function formatTokens(n: number): string {
@@ -259,17 +254,13 @@ export default function AiChatWindow() {
     [roles],
   );
 
-  // #184 phase 1.5: degraded-poll fallback (replaces the F4/F5/F7 latches). When
-  // ChatThread could not attach to a still-running run it arms this via
-  // onResumeFallback(true); the thread disarms it on settle / local stream. The
-  // window only OWNS the timer (armedAtRef stamps when it was armed for the cap).
+  // #184 phase 1.5 / #488: degraded-poll fallback. ChatThread's FSM arms this via
+  // onResumeFallback(true) when it enters a poll-bearing recovery (attach 204 /
+  // starved finish / stop) and disarms it on settle / local stream / stalled. The
+  // 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,32 +272,63 @@ 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
-      // and while the run is still active (#430: under the INACTIVITY cap, not a
-      // fixed-from-start cap); otherwise off. NO error checks (TanStack v5 resets
-      // fetchFailureCount each fetch, so consecutive errors are not expressible —
-      // and the poll must survive a server restart) and NO tail checks (the
-      // 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.
+      // #491: the full infinite-query no longer POLLS. It seeds the thread ONCE; the
+      // degraded fallback now runs a DELTA poller (below) that augments THIS cache
+      // idempotently, instead of refetching every page (with full parts) every 2.5s.
+      false,
+      // #344: gate on windowOpen too — no message history is fetched while the window
+      // is closed; it loads when the window opens with an active chat.
       windowOpen,
     );
 
-  // #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.
+  // #491 degraded DELTA poll. While armed (degradedPoll) and the window is open on a
+  // chat, poll POST /ai-chat/messages/delta every 2.5s: it returns only the rows
+  // CHANGED since the previous cursor (+ the run fact) in ONE round-trip. We merge
+  // those rows into the SAME infinite-query cache the thread reads (idempotently by
+  // id — the delta's overlap window re-delivers rows), so the thread's reconcile
+  // effect follows the detached run to its terminal row from a fraction of the wire
+  // cost. The run-fact settle stays the thread FSM's job (row-status reconcile), so
+  // we do NOT double-poll /run here. Cursor resets when the chat changes / disarms.
+  const deltaCursorRef = useRef<string | undefined>(undefined);
   useEffect(() => {
-    if (degradedPoll) lastActivityAtRef.current = Date.now();
-  }, [degradedPoll, messageRows]);
+    deltaCursorRef.current = undefined;
+  }, [activeChatId, degradedPoll]);
+  useEffect(() => {
+    if (!degradedPoll || !windowOpen || !activeChatId) return;
+    const chatId = activeChatId;
+    let cancelled = false;
+    const tick = async (): Promise<void> => {
+      try {
+        const res = await getAiChatMessagesDelta(chatId, deltaCursorRef.current);
+        if (cancelled) return;
+        deltaCursorRef.current = res.cursor;
+        if (res.rows.length > 0) {
+          queryClient.setQueryData(
+            AI_CHAT_MESSAGES_RQ_KEY(chatId),
+            (
+              old:
+                | {
+                    pages: { items: IAiChatMessageRow[]; meta: unknown }[];
+                    pageParams: unknown[];
+                  }
+                | undefined,
+            ) =>
+              old
+                ? { ...old, pages: mergeDeltaRowsIntoPages(old.pages, res.rows) }
+                : old,
+          );
+        }
+      } catch {
+        // Transient failure (e.g. a server restart mid-run): swallow and retry on
+        // the next tick — the poll must survive a bounce, like the old dumb refetch.
+      }
+    };
+    const id = setInterval(() => void tick(), 2500);
+    return () => {
+      cancelled = true;
+      clearInterval(id);
+    };
+  }, [degradedPoll, windowOpen, activeChatId, queryClient]);
 
   // #184 reconnect-and-live-follow. Whether detached agent runs are enabled for
   // this workspace. When the feature is off no runs are ever created, so the

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

@@ -57,6 +57,50 @@ export async function stopRun(
   return req.data;
 }
 
+/**
+ * Delta poll (#491): the chat's message rows changed since `cursor` (a DB-clock
+ * timestamp echoed from the previous poll) plus the current run fact, in ONE
+ * round-trip — the degraded-poll fallback's payload, replacing the old "refetch
+ * ALL infinite-query pages every 2.5s with full parts" poll. Omit `cursor` on the
+ * first poll (returns just a fresh cursor, no rows, to start the chain). The
+ * overlap window guarantees occasional REPEATS, so the caller MUST merge rows
+ * idempotently by id (mergeById). Owner-gated server-side.
+ */
+export async function getAiChatMessagesDelta(
+  chatId: string,
+  cursor?: string,
+): Promise<{
+  rows: IAiChatMessageRow[];
+  cursor: string;
+  run: { id: string; status: string } | null;
+}> {
+  const req = await api.post<{
+    rows: IAiChatMessageRow[];
+    cursor: string;
+    run: { id: string; status: string } | null;
+  }>("/ai-chat/messages/delta", { chatId, cursor });
+  return req.data;
+}
+
+/**
+ * #488: the run-fact — "is a run active on this chat?" — first-class from the
+ * server (POST /ai-chat/run). Called on mount to seed the client FSM's run-fact
+ * 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,190 @@
+# 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) |
+| `POLL_IDLE_CAP` (inactivity cap) | stopping | idle | `[disarmPoll, cancelReconnect]`, runFact←null (Review #4: a Stop-armed poll with no SDK/terminal backstop gets a bounded exit — NOT `stalled`, Stop was already pressed so nothing to retry) |
+| `RUN_FACT{null}` (POST /run → null/terminal, 204) | reconnecting/attaching/polling/stopping | idle | `[cancelReconnect, disarmPoll]`, runFact←null (I3 fresh-negative gate) |
+| `RUN_FACT{runId}` | any | (same) | runFact←runId (pessimism toward an attempt) |
+| `STOP_REQUESTED` (user Stop) | streaming, reconnecting, polling | stopping **†** | `[stopRun, abortAttach, cancelReconnect, armPoll]` (poll drives the terminal — I4 exit by data) |
+| `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–15 | `anchorRef {id, stepsPersisted}` | **data** (attachStrategy) | #491 tail-only: replaced `stripRef`/`strippedRowRef`. The PERSISTED assistant row that pins the run (server invariant 6) + its step frontier N; feeds `?anchor=<id>&n=<stepsPersisted>`. No strip — the seed keeps every row; entering reconnecting re-seeds from persist |
+| 16 | `attachAbortRef` | **effect-owned controller** | aborted by the `abortAttach` effect in cleanup (I5) |
+| 17–25 | `chatIdRef`, `openPageRef`, `getEditorSelectionRef`, `roleIdRef`, `stableIdRef`, `queuedRef`, `sendMessageRef`, `statusRef`, `lastForwardedChatIdRef` | **data** (identity/send mirrors) | unchanged — not lifecycle flags |
+| NEW | `pendingSupersedeRef` | **data** (send-plumbing) | the runId injected into the next `POST /stream {supersede}`; the single replacement for the 3 DELETED one-shots (#8/#9/#10) — net −2 refs |
+| 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 (#491, implemented):** the degraded poll now hits the delta endpoint
+   (`POST /ai-chat/messages/delta`), which ALREADY carries the run fact
+   (`run: {id, status} | null`) alongside the changed rows. The client does NOT yet
+   consume that run field — it still drives to a terminal ROW (merged by id),
+   dispatched as `POLL_TERMINAL` — so the run field rides the wire for a future
+   client that settles straight off it.
+
+Pessimism rule: a stale-but-positive fact PERMITS entering recovery (attach); the
+204 then cuts it. A fresh negative fact gates recovery OUT immediately.
+
+---
+
+## 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** is behind the `resumeStream` effect; #491 swapped it to
+  tail-only (`?anchor=&n=`, `anchorRef` data) WITHOUT touching the FSM. Entering
+  reconnecting always re-seeds from persist; on a getRun failure the live partial
+  is dropped + replay-from-start so it is never the tail-apply base (no #137/#161
+  duplication).
+- **Queue** stays a data structure; flush/interrupt decisions are transitions.

apps/client/src/features/ai-chat/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/types/ai-chat.types.ts

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

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

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

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

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

@@ -42,6 +42,70 @@ 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 token-degeneration abort under the SAME 'Response stopped.' marker the live view shows (#495)", () => {
+    // The exact reason the server persists in metadata.error on a degeneration
+    // abort (ai-chat.service OUTPUT_DEGENERATION_ERROR). Live, this event shows
+    // the neutral "Response stopped." notice; the persisted banner MUST match it
+    // so live and refetch never disagree.
+    const view = describeChatError(
+      "Output degeneration detected (repeated token loop)",
+      t,
+    );
+    expect(view.title).toBe("Response stopped.");
+    expect(view.detail).toBe(
+      "The answer was stopped automatically because the model fell into a repeated output loop.",
+    );
+    // Regression guard: it must NOT fall through to the generic heading.
+    expect(view.title).not.toBe("Something went wrong");
+  });
+
   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,60 @@ 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.",
+      ),
+    };
+  }
+
+  // Our own token-degeneration abort (#444): the server aborts a runaway
+  // repetition loop and persists this exact reason in metadata.error. LIVE, the
+  // same abort surfaces as the neutral "Response stopped." notice (the client
+  // cannot tell it from a manual Stop mid-stream), so the persisted banner must
+  // read the SAME "Response stopped." marker — otherwise the live view and a
+  // later refetch show two different texts for one event. The detail explains the
+  // loop-guard cause without contradicting the shared heading.
+  if (/output degeneration detected|repeated token loop/i.test(msg)) {
+    return {
+      title: t("Response stopped."),
+      detail: t(
+        "The answer was stopped automatically because the model fell into a repeated output loop.",
+      ),
+    };
+  }
+
   if (/"statusCode"\s*:\s*403\b/.test(msg)) {
     return {
       title: t("AI chat is disabled"),

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

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

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

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

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

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

apps/client/src/features/editor/atoms/editor-atoms.ts

@@ -3,11 +3,20 @@ import { atom } from "jotai";
 // import would drag the whole @tiptap/core engine into the eager graph of every
 // shell component that reads one of these atoms.
 import type { Editor } from "@tiptap/core";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 
 export const pageEditorAtom = atom<Editor | null>(null);
 
+// #370 — the active page's collab provider, published by the page editor so the
+// header menu can emit the "save-version" stateless signal (Cmd+S / button).
+// Null when the page is read-only / collab isn't connected. A typed initial
+// value (rather than an explicit generic) keeps jotai's overload resolution on
+// the writable PrimitiveAtom branch.
+const initialCollabProvider: HocuspocusProvider | null = null;
+export const collabProviderAtom = atom(initialCollabProvider);
+
 export const titleEditorAtom = atom<Editor | null>(null);
 
 export const readOnlyEditorAtom = atom<Editor | null>(null);

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import * as Y from "yjs";
+import { yHistoryAvailability } from "./use-toolbar-state.ts";
+
+// Undo/redo availability is derived from the Yjs UndoManager's PRIVATE
+// `undoStack` / `redoStack` fields (see use-toolbar-state.ts for why we read the
+// stack lengths directly instead of the expensive `editor.can().undo()` dry-run).
+// These tests lock in the behavior AND pin the library shape so a yjs / y-undo
+// upgrade that renames/restructures those internals fails loudly here rather than
+// silently enabling/disabling the toolbar buttons in production.
+describe("yHistoryAvailability", () => {
+  it("reports availability from the stack lengths", () => {
+    expect(yHistoryAvailability({ undoStack: [], redoStack: [] })).toEqual({
+      canUndo: false,
+      canRedo: false,
+    });
+    expect(
+      yHistoryAvailability({ undoStack: [{}], redoStack: [] }),
+    ).toEqual({ canUndo: true, canRedo: false });
+    expect(
+      yHistoryAvailability({ undoStack: [{}], redoStack: [{}, {}] }),
+    ).toEqual({ canUndo: true, canRedo: true });
+  });
+
+  it("returns null when the private stack shape is unrecognized (upgrade guard)", () => {
+    // Simulates a yjs / y-undo upgrade that renames or restructures the private
+    // fields: the caller then falls back to the safe prosemirror-history default
+    // instead of throwing on `.length` of undefined or reading garbage.
+    expect(yHistoryAvailability(undefined)).toBeNull();
+    expect(yHistoryAvailability(null)).toBeNull();
+    expect(yHistoryAvailability({})).toBeNull();
+    expect(yHistoryAvailability({ undoStack: 5, redoStack: 5 })).toBeNull();
+    // Only one stack present (partial rename) is still not trusted.
+    expect(yHistoryAvailability({ undoStack: [] })).toBeNull();
+  });
+
+  it("pin-test: a real yjs UndoManager still exposes undoStack/redoStack arrays", () => {
+    const doc = new Y.Doc();
+    const text = doc.getText("prosemirror");
+    const undoManager = new Y.UndoManager(text);
+
+    // Fresh manager: both stacks empty -> nothing to undo/redo.
+    expect(yHistoryAvailability(undoManager)).toEqual({
+      canUndo: false,
+      canRedo: false,
+    });
+
+    // A tracked edit must push onto the private undoStack. If a future yjs
+    // renames these fields, yHistoryAvailability(undoManager) returns null and
+    // the expectation below fails loudly.
+    text.insert(0, "hello");
+    undoManager.stopCapturing();
+    expect(yHistoryAvailability(undoManager)).toEqual({
+      canUndo: true,
+      canRedo: false,
+    });
+
+    // Undoing moves the item to the redoStack -> redo becomes available.
+    undoManager.undo();
+    expect(yHistoryAvailability(undoManager)).toEqual({
+      canUndo: false,
+      canRedo: true,
+    });
+  });
+});

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.ts

@@ -35,6 +35,30 @@ export interface ToolbarState {
 // When neither history backend is installed (the pre-sync static editor —
 // mainExtensions only, undoRedo disabled), both fall through to 0 -> false,
 // matching the previous `safeCan` behavior.
+// Reads the Yjs UndoManager's undo/redo availability from its stack lengths.
+//
+// `undoStack` / `redoStack` are PRIVATE y-undo / yjs internals, so we touch them
+// defensively: a yjs or y-undo upgrade that renames or restructures these fields
+// must not silently mis-drive the toolbar buttons (nor throw on `.length` of
+// `undefined`). We only trust them when they are actually arrays; otherwise this
+// returns null and the caller falls back to a safe default. The pin-test in
+// use-toolbar-state.test.ts asserts the current library shape, so an upgrade that
+// breaks this contract fails loudly there instead of failing silently in the UI.
+export function yHistoryAvailability(
+  undoManager: unknown,
+): { canUndo: boolean; canRedo: boolean } | null {
+  if (!undoManager || typeof undoManager !== "object") return null;
+  const { undoStack, redoStack } = undoManager as {
+    undoStack?: unknown;
+    redoStack?: unknown;
+  };
+  if (!Array.isArray(undoStack) || !Array.isArray(redoStack)) return null;
+  return {
+    canUndo: undoStack.length > 0,
+    canRedo: redoStack.length > 0,
+  };
+}
+
 function historyAvailability(editor: Editor): {
   canUndo: boolean;
   canRedo: boolean;
@@ -43,16 +67,14 @@ function historyAvailability(editor: Editor): {
 
   // Collaboration history (Yjs) takes precedence when present.
   const yState = yUndoPluginKey.getState(state) as
-    | { undoManager?: { undoStack: unknown[]; redoStack: unknown[] } }
+    | { undoManager?: unknown }
     | undefined;
-  if (yState?.undoManager) {
-    return {
-      canUndo: yState.undoManager.undoStack.length > 0,
-      canRedo: yState.undoManager.redoStack.length > 0,
-    };
-  }
+  const yAvail = yHistoryAvailability(yState?.undoManager);
+  if (yAvail) return yAvail;
 
   // Plain prosemirror-history (returns 0 when the history plugin is absent).
+  // This is also the safe default when a Yjs UndoManager is present but its
+  // private stack shape is no longer recognized (yHistoryAvailability -> null).
   return {
     canUndo: undoDepth(state) > 0,
     canRedo: redoDepth(state) > 0,

apps/client/src/features/editor/gitmost/gitmost-recording.test.ts

@@ -9,7 +9,7 @@ import { Italic } from "@tiptap/extension-italic";
 import { Link } from "@tiptap/extension-link";
 import { gitmostInsertTranscriptIntoEditor } from "./gitmost-recording.ts";
 
-const ZWSP = "​"; // U+200B, the helper's block-trigger neutralizer
+const ZWSP = "​"; // U+200B — asserted ABSENT (the block-escape lives in the serializer now)
 
 /**
  * #377 — the web-side bridge must append the native host's transcript below the
@@ -18,8 +18,9 @@ const ZWSP = "​"; // U+200B, the helper's block-trigger neutralizer
  * regression would be caught), asserting the resulting document rather than
  * mocking the editor: transcript present -> "Transcript" heading + one paragraph
  * per non-empty line; content is inserted as LITERAL TEXT (no HTML/markdown
- * parsing); col-0 markdown block triggers are neutralized so git-sync keeps them
- * paragraphs; absent/empty/non-string -> no-op.
+ * parsing); col-0 markdown block triggers are stored verbatim (the git-sync
+ * serializer block-escapes them, so no client-side ZWSP is needed);
+ * absent/empty/non-string -> no-op.
  */
 describe("gitmostInsertTranscriptIntoEditor", () => {
   const makeEditor = () =>
@@ -91,19 +92,22 @@ describe("gitmostInsertTranscriptIntoEditor", () => {
     editor.destroy();
   });
 
-  it("neutralizes col-0 markdown block triggers with a leading ZWSP (git-sync safety)", () => {
+  it("inserts col-0 markdown block triggers as verbatim paragraph text (no ZWSP workaround)", () => {
     const editor = makeEditor();
-    // Trigger lines (some with a leaked indent) + a normal prefixed line.
+    // Trigger lines (some with a leaked indent) + a normal prefixed line. The
+    // git-sync serializer now block-escapes a leading trigger itself, so the
+    // bridge inserts each line's TEXT byte-exact (only the leaked indent is
+    // trimmed) — no invisible ZWSP is prepended anymore.
     const inserted = gitmostInsertTranscriptIntoEditor(
       editor,
       [
         "- dash",
-        "  > quote", // leading indent must be trimmed then neutralized
+        "  > quote", // leading indent is trimmed, text otherwise verbatim
         "# hash",
         "1. one",
         "> [!info] note",
         "```js",
-        "---", // solid thematic break -> horizontalRule (text-losing) if unneutralized
+        "---",
         "***",
         "___",
         "You: normal line",
@@ -116,20 +120,23 @@ describe("gitmostInsertTranscriptIntoEditor", () => {
       .map((n: any) => n.content?.[0]?.text)
       .filter((t: any) => typeof t === "string") as string[];
 
-    // Every block-trigger line is prefixed with the invisible ZWSP (indent
-    // trimmed first); the normal `You:` line is left byte-exact.
+    // Each trigger line is stored as its own byte-exact text (indent trimmed);
+    // the git-sync round-trip keeps it a paragraph via the serializer's
+    // block-escape, so no ZWSP is needed here.
     expect(texts).toEqual([
-      ZWSP + "- dash",
-      ZWSP + "> quote",
-      ZWSP + "# hash",
-      ZWSP + "1. one",
-      ZWSP + "> [!info] note",
-      ZWSP + "```js",
-      ZWSP + "---",
-      ZWSP + "***",
-      ZWSP + "___",
+      "- dash",
+      "> quote",
+      "# hash",
+      "1. one",
+      "> [!info] note",
+      "```js",
+      "---",
+      "***",
+      "___",
       "You: normal line",
     ]);
+    // Guard: no invisible ZWSP leaked into any inserted line.
+    for (const t of texts) expect(t).not.toContain(ZWSP);
 
     editor.destroy();
   });

apps/client/src/features/editor/gitmost/gitmost-recording.ts

@@ -240,45 +240,22 @@ export async function gitmostUploadFileToEditor(
   }
 }
 
-// Zero-width space (U+200B). Prepended to a transcript line that begins with a
-// markdown BLOCK trigger: it is invisible in the rendered doc but shifts the
-// trigger off column 0, so the git-sync doc->markdown->doc round-trip keeps the
-// line a plain paragraph (see GITMOST_MD_BLOCK_TRIGGER_RE).
-const GITMOST_ZWSP = "​";
-
-// A markdown BLOCK-level construct that, sitting at column 0 of a paragraph
-// line, the git-sync markdown serializer (packages/prosemirror-markdown
-// markdown-converter.ts, `case "paragraph"`) would re-parse into a NON-paragraph
-// block on the doc->markdown->doc cycle. That serializer emits paragraph text
-// verbatim with NO block-escape (the pre-existing root cause), so a leading
-// `#`/`-`/`*`/`+`/`>`, an ordered-list `N.`/`N)`, a code fence ```/~~~, a table
-// `|`, or a `> [!info]` callout opener would silently become a heading / list /
-// quote / code block / table / callout. The final alternative matches a WHOLE-
-// LINE thematic break — solid `---`/`***`/`___` or spaced `- - -`/`_ _ _` (3+ of
-// the same `-`/`*`/`_`) — which round-trips into a `horizontalRule`; because
-// that node carries NO text, an un-neutralized separator line would LOSE its
-// text entirely (worse than the list/quote case). This matches a TRIMMED line's
-// start; the transcript's own `You:` / `Speaker N:` prefix begins with a letter
-// and never matches, so prefixed lines are left byte-exact.
-const GITMOST_MD_BLOCK_TRIGGER_RE =
-  /^(?:#{1,6}(?:\s|$)|[-*+](?:\s|$)|>|\d+[.)](?:\s|$)|```|~~~|\||([-*_])(?:\s*\1){2,}\s*$)/;
-
 // Append a transcript block BELOW the recording's audio node in a live editor:
 // a "Transcript" heading followed by one paragraph per non-empty transcript
 // line. The transcript is plain text, `\n`-separated, each line already
 // formatted as `You: ...` / `Speaker N: ...` by the native host — line text is
 // inserted as a TEXT node (never HTML/markdown), so there is no injection or
 // mark-parsing surface. Each kept line is trimmed (drops an indent that would
-// both leak into the display and, at col 0, form a markdown block trigger) and,
-// if it still begins with a col-0 markdown block trigger, gets an invisible
-// zero-width space prepended so the git-sync round-trip cannot turn it into a
-// list/quote/heading/callout/code/table (defensive boundary against the
-// serializer's missing block-escape). This is best-effort and meant to run
-// AFTER the audio has already been inserted; the caller must guard against a
-// throw so a transcript failure never fails the (already successful) recording.
-// Returns true when a block was inserted, false when there was nothing to
-// insert (transcript undefined/empty/not-a-string). A non-string value is a
-// no-op, not an error.
+// leak into the display). A line that begins with a col-0 markdown block
+// trigger (`#`/`-`/`>`/`1.`/fence/`---`/…) needs no client-side workaround: the
+// git-sync serializer (packages/prosemirror-markdown, `case "paragraph"`) now
+// block-escapes such a leading trigger, so the doc->markdown->doc round-trip
+// keeps the line a paragraph on its own — the former invisible-ZWSP defense is
+// gone. This is best-effort and meant to run AFTER the audio has already been
+// inserted; the caller must guard against a throw so a transcript failure never
+// fails the (already successful) recording. Returns true when a block was
+// inserted, false when there was nothing to insert (transcript
+// undefined/empty/not-a-string). A non-string value is a no-op, not an error.
 export function gitmostInsertTranscriptIntoEditor(
   editor: Editor,
   transcript: unknown,
@@ -288,13 +265,7 @@ export function gitmostInsertTranscriptIntoEditor(
     .split("\n")
     // Trim each line and drop blank (whitespace-only) ones.
     .map((line) => line.trim())
-    .filter((line) => line.length > 0)
-    // Neutralize a col-0 markdown block trigger with an invisible ZWSP so the
-    // git-sync round-trip keeps the line a paragraph. Host lines (`You:` /
-    // `Speaker N:`) never match and stay byte-exact.
-    .map((line) =>
-      GITMOST_MD_BLOCK_TRIGGER_RE.test(line) ? GITMOST_ZWSP + line : line,
-    );
+    .filter((line) => line.length > 0);
   if (lines.length === 0) return false;
 
   const content = [

apps/client/src/features/editor/page-editor.tsx

@@ -31,11 +31,18 @@ import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
+  collabProviderAtom,
   currentPageEditModeAtom,
   dictationAvailabilityAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { notifications } from "@mantine/notifications";
+import {
+  VERSION_SAVED_MESSAGE_TYPE,
+  type VersionSavedMessage,
+  saveVersionPending,
+} from "@/features/page-history/version-messages";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
   activeCommentIdAtom,
@@ -124,6 +131,7 @@ export default function PageEditor({
 
   const [currentUser] = useAtom(currentUserAtom);
   const [, setEditor] = useAtom(pageEditorAtom);
+  const setCollabProvider = useSetAtom(collabProviderAtom);
   const [, setAsideState] = useAtom(asideStateAtom);
   const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
   const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
@@ -181,6 +189,24 @@ export default function PageEditor({
       const onStatelessHandler = ({ payload }: onStatelessParameters) => {
         try {
           const message = JSON.parse(payload);
+          // #370 — a version was saved somewhere; live-refresh the history panel
+          // on every client. Only the client that pressed Save (tracked by the
+          // module-level flag) shows the confirmation toast.
+          if (message?.type === VERSION_SAVED_MESSAGE_TYPE) {
+            const versionMsg = message as VersionSavedMessage;
+            queryClient.invalidateQueries({
+              queryKey: ["page-history-list"],
+            });
+            if (saveVersionPending.current) {
+              saveVersionPending.current = false;
+              notifications.show({
+                message: versionMsg.alreadySaved
+                  ? t("Already saved as the latest version")
+                  : t("Version saved"),
+              });
+            }
+            return;
+          }
           if (message?.type !== "page.updated" || !message.updatedAt) return;
           const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
           if (pageData) {
@@ -238,12 +264,16 @@ export default function PageEditor({
 
       local.on("synced", onLocalSyncedHandler);
       providersRef.current = { socket, local, remote };
+      // #370 — publish the provider so the header menu can emit save-version.
+      setCollabProvider(remote);
       setProvidersReady(true);
     } else {
+      setCollabProvider(providersRef.current.remote);
       setProvidersReady(true);
     }
     // Only destroy on final unmount
     return () => {
+      setCollabProvider(null);
       providersRef.current?.socket.destroy();
       providersRef.current?.remote.destroy();
       providersRef.current?.local.destroy();

apps/client/src/features/page-history/components/history-item.tsx

@@ -1,4 +1,11 @@
-import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
+import {
+  Text,
+  Group,
+  UnstyledButton,
+  Avatar,
+  Tooltip,
+  Badge,
+} from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
 import { formattedDate } from "@/lib/time";
@@ -7,36 +14,59 @@ import clsx from "clsx";
 import { IPageHistory } from "@/features/page-history/types/page.types";
 import { memo, useCallback } from "react";
 import { useSetAtom } from "jotai";
+import { useTranslation } from "react-i18next";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
 
 const MAX_VISIBLE_AVATARS = 5;
 
+/**
+ * #370 — map a snapshot's intentionality tier to its badge. `version: true`
+ * marks the intentional points (manual / agent); autosaves (boundary / idle /
+ * legacy null) are non-versions and get dimmed in the list.
+ */
+type HistoryKindMeta = { labelKey: string; color: string; version: boolean };
+export function historyKindMeta(kind?: string | null): HistoryKindMeta {
+  switch (kind) {
+    case "manual":
+      return { labelKey: "Saved", color: "blue", version: true };
+    case "agent":
+      return { labelKey: "Agent version", color: "violet", version: true };
+    case "boundary":
+      return { labelKey: "Boundary", color: "gray", version: false };
+    default: // "idle" | null | undefined (legacy autosave)
+      return { labelKey: "Autosave", color: "gray", version: false };
+  }
+}
+
 interface HistoryItemProps {
   historyItem: IPageHistory;
-  index: number;
-  onSelect: (id: string, index: number) => void;
-  onHover?: (id: string, index: number) => void;
+  // The previous snapshot for diff/restore is resolved by id from the FULL list
+  // in the parent (resolvePrevSnapshotId), so the item only needs to report its
+  // own id — never a list index (which would be the filtered-view index).
+  onSelect: (id: string) => void;
+  onHover?: (id: string) => void;
   onHoverEnd?: () => void;
   isActive: boolean;
 }
 
 const HistoryItem = memo(function HistoryItem({
   historyItem,
-  index,
   onSelect,
   onHover,
   onHoverEnd,
   isActive,
 }: HistoryItemProps) {
   const setHistoryModalOpen = useSetAtom(historyAtoms);
+  const { t } = useTranslation();
+  const kindMeta = historyKindMeta(historyItem.kind);
 
   const handleClick = useCallback(() => {
-    onSelect(historyItem.id, index);
-  }, [onSelect, historyItem.id, index]);
+    onSelect(historyItem.id);
+  }, [onSelect, historyItem.id]);
 
   const handleMouseEnter = useCallback(() => {
-    onHover?.(historyItem.id, index);
-  }, [onHover, historyItem.id, index]);
+    onHover?.(historyItem.id);
+  }, [onHover, historyItem.id]);
 
   const contributors = historyItem.contributors;
   const hasContributors = contributors && contributors.length > 0;
@@ -49,8 +79,20 @@ const HistoryItem = memo(function HistoryItem({
       onMouseEnter={handleMouseEnter}
       onMouseLeave={onHoverEnd}
       className={clsx(classes.history, { [classes.active]: isActive })}
+      // #370 — dim autosnapshots so intentional versions stand out.
+      style={{ opacity: kindMeta.version ? 1 : 0.55 }}
     >
-      <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+      <Group gap={6} wrap="nowrap" justify="space-between">
+        <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+        <Badge
+          size="xs"
+          radius="sm"
+          variant={kindMeta.version ? "filled" : "light"}
+          color={kindMeta.color}
+        >
+          {t(kindMeta.labelKey)}
+        </Badge>
+      </Group>
 
       <Group gap={6} wrap="nowrap" mt={4}>
         {hasContributors ? (

apps/client/src/features/page-history/components/history-list.tsx

@@ -2,14 +2,16 @@ import {
   usePageHistoryListQuery,
   prefetchPageHistory,
 } from "@/features/page-history/queries/page-history-query";
-import HistoryItem from "@/features/page-history/components/history-item";
+import HistoryItem, {
+  historyKindMeta,
+} from "@/features/page-history/components/history-item";
 import {
   activeHistoryIdAtom,
   activeHistoryPrevIdAtom,
   historyAtoms,
 } from "@/features/page-history/atoms/history-atoms";
 import { useAtom, useSetAtom } from "jotai";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   Button,
   ScrollArea,
@@ -17,9 +19,12 @@ import {
   Divider,
   Loader,
   Center,
+  Switch,
+  Text,
 } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import { useHistoryRestore } from "@/features/page-history/hooks";
+import { resolvePrevSnapshotId } from "@/features/page-history/utils/resolve-prev-snapshot";
 
 const PREFETCH_DELAY_MS = 150;
 
@@ -47,6 +52,22 @@ function HistoryList({ pageId }: Props) {
     [pageHistoryData],
   );
 
+  // #370 — "only versions" filter: hide autosnapshots (idle/boundary/legacy
+  // null), keep only intentional points (manual/agent). Filtering is over the
+  // already-loaded pages; the diff/restore still targets the true previous
+  // snapshot, so items carry their index within the FULL list.
+  const [onlyVersions, setOnlyVersions] = useState(false);
+  // Reuse historyKindMeta().version — the SAME predicate the badge (HistoryItem)
+  // uses to mark intentional points — so the "Only versions" filter and the badge
+  // can never drift apart when a future intentional kind is added.
+  const visibleItems = useMemo(
+    () =>
+      onlyVersions
+        ? historyItems.filter((item) => historyKindMeta(item.kind).version)
+        : historyItems,
+    [historyItems, onlyVersions],
+  );
+
   const loadMoreRef = useRef<HTMLDivElement>(null);
   const prefetchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
@@ -60,11 +81,13 @@ function HistoryList({ pageId }: Props) {
   }, []);
 
   const handleHover = useCallback(
-    (historyId: string, index: number) => {
+    (historyId: string) => {
       clearPrefetchTimeout();
       prefetchTimeoutRef.current = setTimeout(() => {
         prefetchPageHistory(historyId);
-        const prevId = historyItems[index + 1]?.id;
+        // The true previous snapshot in the FULL list (not the previous visible
+        // one under the "only versions" filter).
+        const prevId = resolvePrevSnapshotId(historyItems, historyId);
         if (prevId) {
           prefetchPageHistory(prevId);
         }
@@ -78,9 +101,11 @@ function HistoryList({ pageId }: Props) {
   }, [clearPrefetchTimeout]);
 
   const handleSelect = useCallback(
-    (id: string, index: number) => {
+    (id: string) => {
       setActiveHistoryId(id);
-      setActiveHistoryPrevId(historyItems[index + 1]?.id ?? "");
+      // Baseline = true previous snapshot in the FULL list, so the "only
+      // versions" filter never diffs/restores against the wrong item.
+      setActiveHistoryPrevId(resolvePrevSnapshotId(historyItems, id));
     },
     [historyItems, setActiveHistoryId, setActiveHistoryPrevId],
   );
@@ -128,12 +153,27 @@ function HistoryList({ pageId }: Props) {
 
   return (
     <div>
+      <Group px="xs" py={6} justify="flex-end">
+        <Switch
+          size="xs"
+          checked={onlyVersions}
+          onChange={(e) => setOnlyVersions(e.currentTarget.checked)}
+          label={t("Only versions")}
+        />
+      </Group>
+
       <ScrollArea h={620} w="100%" type="scroll" scrollbarSize={5}>
-        {historyItems.map((historyItem, index) => (
+        {onlyVersions && visibleItems.length === 0 && (
+          <Center py="md">
+            <Text size="sm" c="dimmed">
+              {t("No saved versions yet.")}
+            </Text>
+          </Center>
+        )}
+        {visibleItems.map((historyItem) => (
           <HistoryItem
             key={historyItem.id}
             historyItem={historyItem}
-            index={index}
             onSelect={handleSelect}
             onHover={handleHover}
             onHoverEnd={clearPrefetchTimeout}

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

@@ -24,6 +24,10 @@ export interface IPageHistory {
   updatedAt: string;
   lastUpdatedBy: IPageHistoryUser;
   contributors?: IPageHistoryUser[];
+  // #370 — intentionality tier: 'manual'/'agent' are versions (intentional
+  // points), 'idle'/'boundary' are autosnapshots; null/undefined = legacy
+  // autosave. Derived server-side, drives the history badge + "versions" filter.
+  kind?: "manual" | "agent" | "idle" | "boundary" | null;
   // Provenance markers copied off the page row when the snapshot was saved.
   // `'agent'` marks a version written by the AI agent; `lastUpdatedAiChatId`
   // (when present) deep-links to the chat that produced the edit.

apps/client/src/features/page-history/utils/resolve-prev-snapshot.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { resolvePrevSnapshotId } from "./resolve-prev-snapshot";
+
+// #370 F4 — the risky client path: with the "only versions" filter active, diff
+// and restore must still baseline against the TRUE previous snapshot in the FULL
+// list, never the previous VISIBLE version (which would skip the autosnapshots
+// between two versions). These pin that the resolution is by FULL-list order.
+describe("resolvePrevSnapshotId", () => {
+  // Newest-first, as the history list stores it: a version, then two autosaves,
+  // then an older version.
+  const full = [
+    { id: "v2", kind: "manual" },
+    { id: "a2", kind: "idle" },
+    { id: "a1", kind: "boundary" },
+    { id: "v1", kind: "manual" },
+    { id: "a0", kind: null },
+  ];
+
+  it("returns the immediate FULL-list successor, not the previous visible version", () => {
+    // Selecting v2 while filtered to versions-only must baseline against a2 (the
+    // real chronological predecessor), NOT v1 (the previous visible version).
+    expect(resolvePrevSnapshotId(full, "v2")).toBe("a2");
+  });
+
+  it("resolves an autosnapshot's predecessor by full-list order", () => {
+    expect(resolvePrevSnapshotId(full, "a1")).toBe("v1");
+  });
+
+  it("returns '' for the oldest item (no predecessor)", () => {
+    expect(resolvePrevSnapshotId(full, "a0")).toBe("");
+  });
+
+  it("returns '' for an id not in the list", () => {
+    expect(resolvePrevSnapshotId(full, "missing")).toBe("");
+  });
+
+  it("does not depend on a filtered subset — same result whatever is visible", () => {
+    // The helper only ever sees the full list; a filtered view cannot change the
+    // baseline it computes.
+    expect(resolvePrevSnapshotId(full, "v1")).toBe("a0");
+  });
+});

apps/client/src/features/page-history/utils/resolve-prev-snapshot.ts

@@ -0,0 +1,22 @@
+/**
+ * #370 — resolve the TRUE previous snapshot for a history item.
+ *
+ * The history panel can be filtered to "only versions" (manual/agent), but diff
+ * and restore must always compare against the immediately-preceding snapshot in
+ * the FULL, unfiltered list — NOT the previous VISIBLE item. Comparing against
+ * the previous visible version would silently skip the autosnapshots between two
+ * versions and diff/restore the wrong baseline.
+ *
+ * Given the full (newest-first) list and an item id, this returns the id of the
+ * item right after it in the full list (its chronological predecessor), or "" if
+ * it is the oldest / not found. Pure and list-order-preserving so it can be unit
+ * tested without mounting the component.
+ */
+export function resolvePrevSnapshotId(
+  fullItems: ReadonlyArray<{ id: string }>,
+  id: string,
+): string {
+  const index = fullItems.findIndex((item) => item.id === id);
+  if (index === -1) return "";
+  return fullItems[index + 1]?.id ?? "";
+}

apps/client/src/features/page-history/version-messages.ts

@@ -0,0 +1,28 @@
+/**
+ * #370 — page-version stateless wire formats. Kept in one place so the client
+ * emitter (Save hotkey / button) and the client listener (page-editor) agree
+ * with the server (PersistenceExtension) on the message shapes.
+ */
+
+/** Client → server: "save a version now". The server derives the tier
+ * (manual/agent) from the signed connection actor, never from this payload. */
+export const SAVE_VERSION_MESSAGE_TYPE = "save-version";
+
+/** Server → all clients: a version was saved (or promoted / already existed). */
+export const VERSION_SAVED_MESSAGE_TYPE = "version.saved";
+
+export interface VersionSavedMessage {
+  type: typeof VERSION_SAVED_MESSAGE_TYPE;
+  historyId: string;
+  kind: "manual" | "agent";
+  /** True when the latest snapshot was already a manual version (a no-op save). */
+  alreadySaved: boolean;
+}
+
+/**
+ * Cross-component coordination flag so only the client that pressed Save shows
+ * the confirmation toast, while every other client silently refreshes its
+ * history panel on the broadcast. A module-level ref avoids stale-closure
+ * pitfalls in the editor's long-lived stateless handler.
+ */
+export const saveVersionPending = { current: false };

apps/client/src/features/page/components/header/page-header-menu.tsx

@@ -3,6 +3,7 @@ import {
   IconArrowRight,
   IconArrowsHorizontal,
   IconClockHour4,
+  IconDeviceFloppy,
   IconDots,
   IconEye,
   IconEyeOff,
@@ -17,7 +18,7 @@ import {
   IconTrash,
   IconWifiOff,
 } from "@tabler/icons-react";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import { useAsideTriggerProps } from "@/hooks/use-toggle-aside.tsx";
 import { useAtom, useAtomValue } from "jotai";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
@@ -39,9 +40,14 @@ import { Trans, useTranslation } from "react-i18next";
 import ExportModal from "@/components/common/export-modal";
 import { convertProseMirrorToMarkdown } from "@docmost/prosemirror-markdown/browser";
 import {
+  collabProviderAtom,
   pageEditorAtom,
   yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms.ts";
+import {
+  SAVE_VERSION_MESSAGE_TYPE,
+  saveVersionPending,
+} from "@/features/page-history/version-messages.ts";
 import { formattedDate } from "@/lib/time.ts";
 import { PageEditModeToggle } from "@/features/user/components/page-state-pref.tsx";
 import MovePageModal from "@/features/page/components/move-page-modal.tsx";
@@ -72,9 +78,34 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
   });
   const isDeleted = !!page?.deletedAt;
   const [workspace] = useAtom(workspaceAtom);
+  const collabProvider = useAtomValue(collabProviderAtom);
   // Community public-sharing entry point (replaces the removed EE PageShareModal)
   const workspaceSharingDisabled = workspace?.settings?.sharing?.disabled === true;
 
+  // #370 — explicit "save a version" (Cmd+S / Save button). One path for the
+  // human; the server derives the tier from the signed actor. Readers can't save
+  // (the button is hidden and the collab connection is read-only server-side).
+  const handleSaveVersion = useCallback(() => {
+    if (readOnly || !collabProvider) return;
+    // Flag this client as the initiator so only it shows the confirmation toast;
+    // a safety timeout clears it if no broadcast comes back (e.g. offline).
+    saveVersionPending.current = true;
+    window.setTimeout(() => {
+      saveVersionPending.current = false;
+    }, 5000);
+    collabProvider.sendStateless(
+      JSON.stringify({ type: SAVE_VERSION_MESSAGE_TYPE }),
+    );
+  }, [readOnly, collabProvider]);
+
+  // mod+S must also block the browser's "Save page" dialog. `triggerOnContent-
+  // Editable` + empty ignore-list so it fires while typing in the editor/title.
+  useHotkeys(
+    [["mod+S", handleSaveVersion, { preventDefault: true }]],
+    [],
+    true,
+  );
+
   useHotkeys(
     [
       [
@@ -133,15 +164,16 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
         </ActionIcon>
       </Tooltip>
 
-      <PageActionMenu readOnly={readOnly} />
+      <PageActionMenu readOnly={readOnly} onSaveVersion={handleSaveVersion} />
     </>
   );
 }
 
 interface PageActionMenuProps {
   readOnly?: boolean;
+  onSaveVersion?: () => void;
 }
-function PageActionMenu({ readOnly }: PageActionMenuProps) {
+function PageActionMenu({ readOnly, onSaveVersion }: PageActionMenuProps) {
   const { t } = useTranslation();
   const [, setHistoryModalOpen] = useAtom(historyAtoms);
   const clipboard = useClipboard({ timeout: 500 });
@@ -303,6 +335,20 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
             </Group>
           </Menu.Item>
 
+          {!readOnly && (
+            <Menu.Item
+              leftSection={<IconDeviceFloppy size={16} />}
+              onClick={onSaveVersion}
+              rightSection={
+                <Text size="xs" c="dimmed">
+                  {t("Ctrl+S")}
+                </Text>
+              }
+            >
+              {t("Save version")}
+            </Menu.Item>
+          )}
+
           <Menu.Item
             leftSection={<IconHistory size={16} />}
             onClick={openHistoryModal}

apps/client/src/features/share/components/share-alias-section.test.tsx

@@ -13,8 +13,7 @@ let currentAlias: IShareAlias | null = null;
 let availabilityResult: {
   valid: boolean;
   available: boolean;
-  currentPageId: string | null;
-} = { valid: true, available: true, currentPageId: null };
+} = { valid: true, available: true };
 
 vi.mock("@/features/share/queries/share-query.ts", () => ({
   useShareAliasForPageQuery: () => ({ data: currentAlias }),
@@ -56,7 +55,7 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
   beforeEach(() => {
     setMutateAsync.mockReset();
     currentAlias = null;
-    availabilityResult = { valid: true, available: true, currentPageId: null };
+    availabilityResult = { valid: true, available: true };
   });
 
   it("shows a 'will move it here' HINT (not a terminal error) when the name belongs to another page, and keeps Save enabled", async () => {
@@ -65,7 +64,6 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
     availabilityResult = {
       valid: true,
       available: false,
-      currentPageId: "page-X",
     };
 
     renderSection("page-Y");
@@ -97,7 +95,6 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
     availabilityResult = {
       valid: true,
       available: false,
-      currentPageId: "page-X",
     };
     // The server rejects the un-confirmed save asking the client to confirm.
     setMutateAsync.mockRejectedValueOnce({
@@ -106,7 +103,6 @@ describe("ShareAliasSection — taken-name handling is never a dead end", () =>
         status: 409,
         data: {
           code: "ALIAS_REASSIGN_REQUIRED",
-          currentPageId: "page-X",
           currentPageTitle: "Alias Test Page X",
         },
       },

apps/client/src/features/share/components/share-alias-section.tsx

@@ -48,7 +48,6 @@ export default function ShareAliasSection({
   const [availability, setAvailability] = useState<{
     valid: boolean;
     available: boolean;
-    currentPageId: string | null;
   } | null>(null);
   const [reassign, setReassign] = useState<{
     alias: string;
@@ -76,7 +75,6 @@ export default function ShareAliasSection({
         setAvailability({
           valid: res.valid,
           available: res.available,
-          currentPageId: res.currentPageId,
         });
       } catch {
         setAvailability(null);

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

@@ -108,7 +108,6 @@ export interface IShareAliasAvailability {
   alias: string;
   valid: boolean;
   available: boolean;
-  currentPageId: string | null;
 }
 
 export interface ISharedPageTree {

apps/client/src/features/workspace/components/settings/components/ai-mcp-server-form.tsx

@@ -28,6 +28,7 @@ import {
   IAiMcpServerCreate,
   IAiMcpServerUpdate,
 } from "@/features/workspace/services/ai-mcp-server-service.ts";
+import { resolveToolAllowlist } from "./ai-mcp-server-form.utils.ts";
 
 const formSchema = z.object({
   name: z.string().min(1),
@@ -121,13 +122,20 @@ export default function AiMcpServerForm({
   async function handleSubmit(values: FormValues) {
     const headers = resolveHeaders();
 
+    // An empty tag field means "no restriction" (sent as null) — since #476 the
+    // server persists a literal `[]` as deny-all (zero tools). But a server that
+    // was ALREADY deny-all loads into an empty field too; sending null there
+    // would silently widen it to allow-all on a routine edit, so preserve `[]`.
+    // See resolveToolAllowlist for the full rationale.
+    const toolAllowlist = resolveToolAllowlist(values.toolAllowlist, server);
+
     if (isEdit && server) {
       const payload: IAiMcpServerUpdate = {
         id: server.id,
         name: values.name,
         transport: values.transport,
         url: values.url,
-        toolAllowlist: values.toolAllowlist,
+        toolAllowlist,
         // Always sent: a blank value clears the stored guidance (server -> null).
         instructions: values.instructions,
         enabled: values.enabled,
@@ -140,7 +148,7 @@ export default function AiMcpServerForm({
         name: values.name,
         transport: values.transport,
         url: values.url,
-        toolAllowlist: values.toolAllowlist,
+        toolAllowlist,
         // Blank => server stores null (no guidance).
         instructions: values.instructions,
         enabled: values.enabled,

apps/client/src/features/workspace/components/settings/components/ai-mcp-server-form.utils.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { resolveToolAllowlist } from "./ai-mcp-server-form.utils.ts";
+
+describe("resolveToolAllowlist", () => {
+  it("sends the typed tools when the field is non-empty", () => {
+    expect(resolveToolAllowlist(["a", "b"], { toolAllowlist: null })).toEqual([
+      "a",
+      "b",
+    ]);
+  });
+
+  it("creates as null (unrestricted) when empty and there is no server", () => {
+    expect(resolveToolAllowlist([], undefined)).toBeNull();
+  });
+
+  it("sends null for an empty field on a previously-unrestricted server", () => {
+    expect(resolveToolAllowlist([], { toolAllowlist: null })).toBeNull();
+  });
+
+  it("preserves deny-all: an empty field on a `[]` server stays `[]`, not null", () => {
+    // The core #476/#477 guard: editing a deny-all server (rename/toggle) with
+    // an empty tag field must NOT silently widen it to allow-all.
+    expect(resolveToolAllowlist([], { toolAllowlist: [] })).toEqual([]);
+  });
+
+  it("still sends explicit tools even if the server was deny-all", () => {
+    expect(resolveToolAllowlist(["x"], { toolAllowlist: [] })).toEqual(["x"]);
+  });
+});

apps/client/src/features/workspace/components/settings/components/ai-mcp-server-form.utils.ts

@@ -0,0 +1,22 @@
+import { IAiMcpServer } from "@/features/workspace/services/ai-mcp-server-service.ts";
+
+// Resolve the tool allowlist value to persist from the form field.
+//
+// An empty tag field normally means "no restriction" and is sent as null so
+// the server drops the column (all tools allowed). But a server that was
+// ALREADY deny-all (a stored literal `[]`, meaning zero tools — creatable via
+// the API) loads into the form as an empty field too. Coercing that empty
+// field to null on submit would SILENTLY widen a deny-all server to allow-all
+// on any routine edit (rename, toggle) — the exact silent-widen class #476
+// closed on the read side. So when the edited server was deny-all, preserve
+// `[]` (deny-all); only a genuinely-unrestricted server (stored null/absent)
+// stays null.
+export function resolveToolAllowlist(
+  fieldValue: string[],
+  server?: Pick<IAiMcpServer, "toolAllowlist">,
+): string[] | null {
+  if (fieldValue.length > 0) return fieldValue;
+  const wasDenyAll =
+    Array.isArray(server?.toolAllowlist) && server.toolAllowlist.length === 0;
+  return wasDenyAll ? [] : null;
+}

apps/client/src/features/workspace/components/settings/components/ai-provider-settings.spec.tsx

@@ -6,6 +6,8 @@ import {
   nextReindexPollInterval,
   isReindexComplete,
   isReindexButtonLoading,
+  reindexRunKey,
+  isNewReindexRun,
 } from './ai-provider-settings';
 
 describe('resolveCardStatus', () => {
@@ -221,6 +223,128 @@ describe('isReindexComplete', () => {
   });
 });
 
+describe('reindexRunKey', () => {
+  it('is null when the status carries no run identity', () => {
+    expect(reindexRunKey(undefined)).toBeNull();
+    expect(
+      reindexRunKey({ reindexing: false, indexedPages: 5, totalPages: 5 }),
+    ).toBeNull();
+  });
+
+  it('is null for a legacy/degraded record with an empty runId', () => {
+    // The server sends runId='' for a record written before the field existed;
+    // the client must treat that as "no identity" (fall back to prior behaviour).
+    expect(
+      reindexRunKey({
+        reindexing: true,
+        indexedPages: 0,
+        totalPages: 10,
+        runId: '',
+        reindexStartedAt: 1000,
+      }),
+    ).toBeNull();
+  });
+
+  it('folds runId and startedAt into one stable key', () => {
+    expect(
+      reindexRunKey({
+        reindexing: true,
+        indexedPages: 0,
+        totalPages: 10,
+        runId: 'run-a',
+        reindexStartedAt: 1000,
+      }),
+    ).toBe('run-a:1000');
+  });
+
+  it('changes when the runId changes for the same startedAt', () => {
+    const a = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-a',
+      reindexStartedAt: 1000,
+    });
+    const b = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-b',
+      reindexStartedAt: 1000,
+    });
+    expect(a).not.toBe(b);
+  });
+
+  it('changes when the same runId restarts at a new startedAt', () => {
+    const a = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-a',
+      reindexStartedAt: 1000,
+    });
+    const b = reindexRunKey({
+      reindexing: true,
+      indexedPages: 0,
+      totalPages: 10,
+      runId: 'run-a',
+      reindexStartedAt: 2000,
+    });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('isNewReindexRun (poll keying on runId)', () => {
+  // Derive the status shape from the helper itself so the test needs no export
+  // of the component-internal ReindexStatus type.
+  type ReindexStatusLike = NonNullable<Parameters<typeof reindexRunKey>[0]>;
+  const run = (runId: string, startedAt: number): ReindexStatusLike => ({
+    reindexing: true,
+    indexedPages: 0,
+    totalPages: 10,
+    runId,
+    reindexStartedAt: startedAt,
+  });
+
+  it('first identity after none latched is a NEW run', () => {
+    expect(isNewReindexRun(null, run('run-a', 1000))).toBe(true);
+  });
+
+  it('the SAME identity is not a new run (same run being watched)', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(isNewReindexRun(key, run('run-a', 1000))).toBe(false);
+  });
+
+  it('a DIFFERENT runId is a new run (reset per-run poll state)', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(isNewReindexRun(key, run('run-b', 1000))).toBe(true);
+  });
+
+  it('an identity-less poll (no runId / cleared record) is never a new run', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(
+      isNewReindexRun(key, {
+        reindexing: false,
+        indexedPages: 10,
+        totalPages: 10,
+      }),
+    ).toBe(false);
+  });
+
+  it('a legacy empty-runId poll does not spuriously reset a latched run', () => {
+    const key = reindexRunKey(run('run-a', 1000));
+    expect(
+      isNewReindexRun(key, {
+        reindexing: true,
+        indexedPages: 3,
+        totalPages: 10,
+        runId: '',
+        reindexStartedAt: 1000,
+      }),
+    ).toBe(false);
+  });
+});
+
 describe('isReindexButtonLoading', () => {
   it('loads while the POST mutation is pending', () => {
     expect(

apps/client/src/features/workspace/components/settings/components/ai-provider-settings.tsx

@@ -173,9 +173,43 @@ export function resolveKeyField(
 // Subset of the status payload that drives the reindex poll decisions.
 type ReindexStatus = Pick<
   IAiSettings,
-  "reindexing" | "indexedPages" | "totalPages"
+  "reindexing" | "indexedPages" | "totalPages" | "runId" | "reindexStartedAt"
 >;
 
+/**
+ * A stable per-RUN key for the reindex poll: `runId:startedAt`, or `null` when
+ * the status carries no run identity (no active run, or a legacy/degraded
+ * server record with an empty runId). Two polls of the SAME run share a key; a
+ * new run mints a fresh runId and so a different key.
+ *
+ * This is the single place the client turns the server's run identity into the
+ * value it keys on — it removes the "is this the same run I've been watching or
+ * a brand-new one?" ambiguity that made a class of reindex-status bugs (a stale
+ * pre-reindex snapshot vs a fresh run) get fixed twice (#262). `startedAt` is
+ * folded in so a run that somehow reuses a runId but restarted is still new.
+ */
+export function reindexRunKey(status: ReindexStatus | undefined): string | null {
+  const runId = status?.runId;
+  if (!runId) return null;
+  return `${runId}:${status?.reindexStartedAt ?? ""}`;
+}
+
+/**
+ * Decide whether the latest poll represents a NEW reindex run relative to the
+ * run key the client last latched (`prevKey`, `null` if none yet). True only
+ * when the status carries an identity AND it differs from the latched one — the
+ * signal to reset any per-run poll state (the "seen active" latch / progress the
+ * UI held). The same identity (or no identity) is NOT a new run, so an unchanged
+ * or identity-less poll never resets mid-run.
+ */
+export function isNewReindexRun(
+  prevKey: string | null,
+  status: ReindexStatus | undefined,
+): boolean {
+  const key = reindexRunKey(status);
+  return key !== null && key !== prevKey;
+}
+
 /**
  * Decide the TanStack Query `refetchInterval` while a reindex may be running.
  * Returns the poll interval (ms) to keep polling, or `false` to stop.
@@ -320,6 +354,13 @@ export default function AiProviderSettings() {
   // counter at 0 until a manual reload. A ref (not state) because it must not
   // trigger a render and is only ever read where `reindexing` is already false.
   const reindexSeenActiveRef = useRef(false);
+  // The run identity (runId:startedAt) the current poll window is keyed on. When
+  // a poll reports a DIFFERENT runId the server has started a NEW run, so we
+  // re-latch to it and reset `reindexSeenActiveRef` — a fresh run must never
+  // inherit the previous run's "seen active"/completion state (which would stop
+  // polling immediately or read the old run's counters as this run's). null =
+  // no run keyed yet (steady state, or a legacy record without a runId).
+  const reindexRunKeyRef = useRef<string | null>(null);
 
   // Only admins may read the (masked) AI settings; the server enforces this too.
   const { data: settings, isLoading } = useAiSettingsQuery(isAdmin, (query) =>
@@ -336,6 +377,14 @@ export default function AiProviderSettings() {
   // unmount because the deadline state goes away with the component.
   useEffect(() => {
     if (reindexDeadline === null) return;
+    // Key the poll on the run identity: if this poll carries a runId different
+    // from the one we latched, the server started a NEW run, so adopt it and
+    // drop the per-run "seen active" latch (a fresh run must not inherit the
+    // previous run's completion state). Same runId => same run, leave it alone.
+    if (isNewReindexRun(reindexRunKeyRef.current, settings)) {
+      reindexRunKeyRef.current = reindexRunKey(settings);
+      reindexSeenActiveRef.current = false;
+    }
     // Latch "we have seen the active run" the moment a poll reports it, so the
     // completion check below (and the refetchInterval's) only fires once the run
     // has genuinely started — never on the stale pre-reindex snapshot.
@@ -1220,6 +1269,10 @@ export default function AiProviderSettings() {
                   // immediately.
                   onSuccess: () => {
                     reindexSeenActiveRef.current = false;
+                    // Forget the previous run's identity so the first poll of
+                    // this window (carrying the new run's runId) is recognized
+                    // as a new run and keyed afresh.
+                    reindexRunKeyRef.current = null;
                     setReindexDeadline(Date.now() + REINDEX_POLL_CAP_MS);
                   },
                 })

apps/client/src/features/workspace/services/ai-mcp-server-service.ts

@@ -27,7 +27,9 @@ export interface IAiMcpServerCreate {
   // Auth headers map (e.g. { Authorization: 'Bearer ...' }). Encrypted on save;
   // never returned.
   headers?: Record<string, string>;
-  toolAllowlist?: string[];
+  // Omit/null => no restriction; `[]` is persisted verbatim and means
+  // deny-all (zero tools) since #476.
+  toolAllowlist?: string[] | null;
   // Admin-authored prompt guidance (#180). Blank => stored as null.
   instructions?: string;
   enabled?: boolean;
@@ -43,7 +45,9 @@ export interface IAiMcpServerUpdate {
   transport?: McpTransport;
   url?: string;
   headers?: Record<string, string>;
-  toolAllowlist?: string[];
+  // Absent => unchanged; null => no restriction; `[]` is persisted verbatim
+  // and means deny-all (zero tools) since #476.
+  toolAllowlist?: string[] | null;
   // Admin-authored prompt guidance (#180). Absent => unchanged; blank => cleared.
   instructions?: string;
   enabled?: boolean;

apps/client/src/features/workspace/services/ai-settings-service.ts

@@ -51,6 +51,14 @@ export interface IAiSettings {
   // True while a full workspace reindex is actively running; the counts above
   // then reflect the live run progress (done climbs 0 -> total).
   reindexing?: boolean;
+  // Identity of the ACTIVE reindex run (present only while `reindexing`). The
+  // poll keys on `runId`: a changed value means a NEW run (reset the per-run
+  // poll state the UI latched), the same value is the run already being watched.
+  // Absent/empty ('') => no identity available; the client keeps prior behaviour.
+  runId?: string;
+  // Epoch-ms the active run started; paired with `runId` so a restart with a
+  // recycled id is still detected as a new run.
+  reindexStartedAt?: number;
 }
 
 // Update payload. Key semantics (same for `apiKey` and `embeddingApiKey`):

apps/client/src/lib/telemetry/route-template.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { templateRoute } from "./route-template";
+import { templateRoute, KNOWN_ROUTE_TEMPLATES } from "./route-template";
 
 describe("templateRoute", () => {
   it("templates a space page path (never leaks slugs)", () => {
@@ -32,4 +32,30 @@ describe("templateRoute", () => {
     expect(templateRoute("/weird/unknown/thing")).toBe("other");
     expect(templateRoute("/s/team/p/slug/extra/segments")).toBe("other");
   });
+
+  // The server's /api/telemetry/vitals mirror (ALLOWED_ROUTE_TEMPLATES) drops any
+  // route outside KNOWN_ROUTE_TEMPLATES, so templateRoute must NEVER emit a label
+  // that is not in that dictionary — otherwise legit client metrics get dropped.
+  it("only ever emits labels contained in KNOWN_ROUTE_TEMPLATES (#495)", () => {
+    const samples = [
+      "/",
+      "/home",
+      "/settings/members",
+      "/settings/groups/g-1",
+      "/s/team",
+      "/s/team/trash",
+      "/s/team/p/slug",
+      "/p/slug",
+      "/share/abc",
+      "/share/abc/p/slug",
+      "/share/p/slug",
+      "/labels/urgent",
+      "/invites/inv-1",
+      "/weird/unknown/thing", // -> "other"
+      "/deep/unmatched/x/y/z", // -> "other"
+    ];
+    for (const path of samples) {
+      expect(KNOWN_ROUTE_TEMPLATES.has(templateRoute(path))).toBe(true);
+    }
+  });
 });

apps/client/src/lib/telemetry/route-template.ts

@@ -44,6 +44,22 @@ const STATIC_ROUTES = new Set<string>([
   '/settings/sharing',
 ]);
 
+/**
+ * The COMPLETE, finite vocabulary `templateRoute` can ever emit: the two
+ * synthetic labels (`/` and `other`), the static routes, and the dynamic
+ * templates. Exported so the public `/api/telemetry/vitals` endpoint can reject
+ * any `route` outside this dictionary server-side (the endpoint is anonymous, so
+ * an un-checked `route` is a free-text write surface). The server keeps a mirror
+ * (`ALLOWED_ROUTE_TEMPLATES` in client-metrics.constants.ts) — this is the
+ * canonical source; keep them in lockstep.
+ */
+export const KNOWN_ROUTE_TEMPLATES: ReadonlySet<string> = new Set<string>([
+  '/',
+  'other',
+  ...STATIC_ROUTES,
+  ...ROUTE_PATTERNS.map((p) => p.template),
+]);
+
 export function templateRoute(pathname: string): string {
   // Normalise a trailing slash (except root).
   const path =

apps/client/src/main.tsx

@@ -3,6 +3,7 @@ import "@mantine/spotlight/styles.css";
 import "@mantine/notifications/styles.css";
 import '@mantine/dates/styles.css';
 import "@/styles/a11y-overrides.css";
+import "@/styles/notification-overrides.css";
 
 import ReactDOM from "react-dom/client";
 import App from "./App.tsx";
@@ -47,7 +48,15 @@ function renderApp() {
       <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
         <ModalsProvider>
           <QueryClientProvider client={queryClient}>
-            <Notifications position="bottom-center" limit={3} zIndex={10000} />
+            {/* top-center: toasts sit in the top of the viewport, in the line
+                of sight, and no longer cover centered content (e.g. "Load
+                more"). The below-chrome vertical offset is applied via a
+                position-scoped CSS rule in notification-overrides.css (NOT an
+                inline `style`): Mantine renders all six position containers at
+                once and an inline root style would land on every one, giving the
+                bottom-* containers both top+bottom → full-viewport transparent
+                overlays that swallow clicks. */}
+            <Notifications position="top-center" limit={3} zIndex={10000} />
             <HelmetProvider>
               {/* Root boundary above every lazy route's Suspense: a stale-chunk
                   404 after a deploy is caught and recovered here instead of

apps/client/src/styles/notification-overrides.css

@@ -0,0 +1,64 @@
+/*
+ * Toast (Mantine Notification) visibility overrides.
+ * Mantine renders colorless toasts on --mantine-color-body (== the page
+ * background: white in light mode) with a faint shadow, so on white pages the
+ * card has no visible edge. These rules give every toast a type-tinted
+ * background, a WCAG-checked border and a stronger shadow so it separates from
+ * the page. The [data-mantine-color-scheme] + static-class selector (0,2,0)
+ * beats Mantine's own (0,1,0) rules regardless of stylesheet order (Mantine's
+ * bg/border rules wrap the scheme attribute in :where(), so they stay (0,1,0)).
+ * --notification-color is defined on the same element (defaults to primary,
+ * set per `color` prop), so tint/border follow the toast type. This also covers
+ * the loading/import toast (no accent bar, since the spinner takes the icon
+ * slot): its visibility comes from tone + border + shadow + the colored spinner.
+ */
+
+/*
+ * Push the top-anchored toast containers below the top chrome (fixed 45px
+ * header + optional 45px format toolbar + ~6px gap) so a toast (z-index 10000)
+ * neither covers nor intercepts clicks on the header/toolbar (both z-index 99).
+ *
+ * Scoped to [data-position^='top'] on purpose. Mantine renders ALL SIX position
+ * containers simultaneously (`position` only routes toasts into one via the
+ * store); the root `style` prop would be applied to every one of them by
+ * getStyles("root"). A blanket `top` would land on the bottom-* containers too
+ * (which carry `bottom:16px`) → position:fixed + both edges + height:auto makes
+ * them stretch the full viewport height, and the container root has neither
+ * pointer-events:none nor a background, so those transparent z-10000 overlays
+ * would swallow clicks across the whole page. Restricting to top-* leaves the
+ * bottom containers at height:0.
+ *
+ * Specificity: `.mantine-Notifications-root[data-position^='top']` is (0,2,0)
+ * (class + attribute) and beats Mantine's own top rule
+ * `.m_b37d9ac7:where([data-position='top-center']){top:16px}` which is (0,1,0)
+ * (the :where() contributes 0), regardless of stylesheet order.
+ */
+.mantine-Notifications-root[data-position^='top'] {
+  top: 96px;
+}
+
+[data-mantine-color-scheme='light'] .mantine-Notification-root {
+  /* ~10% type color over white: clearly off-white, text contrast preserved */
+  background-color: color-mix(in srgb, var(--notification-color) 10%, var(--mantine-color-white));
+  /* Border must clear WCAG 3:1 non-text contrast on white. The repo rejects
+     gray-4 for this (a11y-overrides.css); gray-6 base (~3.32:1) darkened by the
+     type color stays >= 3:1. */
+  border: 1px solid color-mix(in srgb, var(--notification-color) 45%, var(--mantine-color-gray-6));
+  box-shadow: var(--mantine-shadow-xl);
+}
+
+[data-mantine-color-scheme='dark'] .mantine-Notification-root {
+  /* Dark page (dark-7/8) vs toast (dark-6) already separate a little; border +
+     shadow carry the type cue here (a 7% dark tint was near-invisible). */
+  background-color: color-mix(in srgb, var(--notification-color) 14%, var(--mantine-color-dark-6));
+  border: 1px solid color-mix(in srgb, var(--notification-color) 45%, var(--mantine-color-dark-3));
+  box-shadow: var(--mantine-shadow-xl);
+}
+
+/* Mantine's message-with-title color is gray-6 (#868e96, already only ~3.32:1
+   on white — below AA 4.5:1); the new tint pushes it lower. Bump to gray-7 to
+   keep multi-line colored toasts readable, consistent with the repo's existing
+   WCAG tuning (theme.ts already bumps this same gray-6 up elsewhere). */
+[data-mantine-color-scheme='light'] .mantine-Notification-description[data-with-title] {
+  color: var(--mantine-color-gray-7);
+}

apps/server/package.json

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

apps/server/src/app.module.ts

@@ -25,7 +25,7 @@ import { CacheModule } from '@nestjs/cache-manager';
 import KeyvRedis from '@keyv/redis';
 import { LoggerModule } from './common/logger/logger.module';
 import { ClsModule } from 'nestjs-cls';
-import { NoopAuditModule } from './integrations/audit/audit.module';
+import { AuditModule } from './integrations/audit/audit.module';
 import { ThrottleModule } from './integrations/throttle/throttle.module';
 import { McpModule } from './integrations/mcp/mcp.module';
 import { SandboxModule } from './integrations/sandbox/sandbox.module';
@@ -55,7 +55,7 @@ try {
       middleware: { mount: true },
     }),
     LoggerModule,
-    NoopAuditModule,
+    AuditModule,
     CoreModule,
     DatabaseModule,
     EnvironmentModule,

apps/server/src/collaboration/constants.ts

@@ -1,10 +1,36 @@
-export const HISTORY_INTERVAL = 5 * 60 * 1000;
-export const HISTORY_FAST_INTERVAL = 60 * 1000;
-export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
-
 // #348 — debounce window for the per-page RAG re-embed job. Repeated saves
 // within this window collapse to a single delayed job (coalesced by a stable
 // jobId), so active editing does not pile up expensive re-embeds (external API
 // + page_embeddings rewrite, concurrency 1). The worker reads the CURRENT page
 // state at run time, so the last content within the window wins.
 export const EMBED_DEBOUNCE_MS = 30 * 1000;
+
+/**
+ * #370 — page-history intentionality tiers. Domain of `page_history.kind`.
+ *   - 'manual' / 'agent'  → Tier 1 versions (intentional points)
+ *   - 'idle' / 'boundary' → Tier 0 autosnapshots (safety net)
+ * A legacy `null` kind is treated as an autosave.
+ */
+export type PageHistoryKind = 'manual' | 'agent' | 'idle' | 'boundary';
+
+/**
+ * #370 — trailing idle-flush windows. A page's pending idle snapshot is
+ * re-armed on every store and fires this long after edits go quiet, so a burst
+ * of edits collapses into a single autosnapshot instead of one-per-store. Human
+ * sessions are noisier and less risky, so they flush less often than the agent.
+ */
+export const IDLE_INTERVAL_USER = 60 * 60 * 1000; // 60m
+export const IDLE_INTERVAL_AGENT = 15 * 60 * 1000; // 15m
+
+/**
+ * #370 — max-wait ceiling for the idle flush. Pure trailing debounce starves the
+ * safety net: hocuspocus stores at least every ~45s, so a CONTINUOUS editing
+ * session would re-arm the trailing timer forever and never take an idle
+ * snapshot until edits finally go quiet (up to IDLE_INTERVAL_USER = 60m). This
+ * ceiling bounds the actual wait from the FIRST edit of a burst, so an idle
+ * snapshot fires at least this often during a long unbroken session — restoring
+ * a recovery point cadence closer to the old heuristic without one-per-store
+ * noise. Mirrors hocuspocus's own maxDebounce idea.
+ */
+export const IDLE_MAX_WAIT_USER = 10 * 60 * 1000; // 10m
+export const IDLE_MAX_WAIT_AGENT = 5 * 60 * 1000; // 5m

apps/server/src/collaboration/extensions/compute-history-job.spec.ts

@@ -1,84 +1,93 @@
+import { computeHistoryJob, resolveSource } from './persistence.extension';
 import {
-  computeHistoryJob,
-  resolveSource,
-} from './persistence.extension';
-import {
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
 } from '../constants';
 
-// A fixed clock + fixed createdAt make pageAge deterministic.
-const NOW = 1_700_000_000_000;
 const PAGE_ID = '550e8400-e29b-41d4-a716-446655440000';
 
-// Build a minimal page whose age (NOW - createdAt) is exactly `ageMs`.
-const pageAged = (ageMs: number) => ({
-  id: PAGE_ID,
-  createdAt: new Date(NOW - ageMs),
-});
+const page = { id: PAGE_ID };
 
-describe('computeHistoryJob', () => {
-  it('agent edit → delay MUST be 0 and job id is source-keyed', () => {
-    // INVARIANT (§15 H2 / persistence.extension): the agent delay MUST stay 0.
-    // The worker re-reads the page row at run time, so any non-zero delay risks
-    // snapshotting content a later human edit has already overwritten. This is
-    // the load-bearing assertion of this spec — do not relax it.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'agent', NOW);
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('agent edit on an OLD page is still delay 0 (age never applies to agents)', () => {
-    // Even when the page is far older than the fast threshold, the agent path
-    // must short-circuit to 0 — age-based debounce is a human-only concern.
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 60_000),
-      'agent',
-      NOW,
-    );
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('human edit on a YOUNG page (age < threshold) → fast interval, bare job id', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD - 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+describe('computeHistoryJob (#370 — shared trailing idle pipeline)', () => {
+  it('human edit → user idle window, bare page.id job', () => {
+    // Humans and the agent now share ONE idle job per page (jobId = page.id).
+    // The agent's old delay=0 fast path is GONE — intentional agent points now
+    // arrive via the explicit save-version signal, not a zero-delay snapshot.
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
     expect(jobId).toBe(PAGE_ID);
   });
 
-  it('human edit on an OLD page (age > threshold) → standard interval', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent edit → agent idle window (shorter), still the bare page.id job', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'agent');
+    expect(delay).toBe(IDLE_INTERVAL_AGENT);
+    // No `-agent` suffix anymore: the agent joins the common idle pipeline.
     expect(jobId).toBe(PAGE_ID);
   });
 
-  it('boundary: pageAge EXACTLY === threshold takes the slow branch (the `<` is strict)', () => {
-    // Off-by-one guard: the condition is `pageAge < HISTORY_FAST_THRESHOLD`, so
-    // an age of exactly the threshold is NOT "fast" — it must use HISTORY_INTERVAL.
-    const { delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent flushes sooner than a human', () => {
+    expect(IDLE_INTERVAL_AGENT).toBeLessThan(IDLE_INTERVAL_USER);
   });
 
-  it('treats any non-"agent" source string as human', () => {
-    // resolveSource only ever yields 'agent' | 'user', but guard the contract:
-    // the agent branch keys strictly on === 'agent'.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'user', NOW);
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+  it('treats any non-"agent" source string as human (keys strictly on === agent)', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
     expect(jobId).toBe(PAGE_ID);
   });
+
+  // #370 review round-1 WARNING: the max-wait ceiling prevents autosnapshot
+  // starvation during a continuous editing session (the trailing timer would
+  // otherwise re-arm forever and never fire).
+  describe('max-wait ceiling', () => {
+    const T0 = 1_000_000; // arbitrary fixed epoch for deterministic tests
+
+    it('once a burst is armed, delay clamps to the remaining max-wait budget', () => {
+      // 1 minute into the burst the USER interval (60m) far exceeds the remaining
+      // max-wait budget (10m - 1m = 9m), so the delay is clamped DOWN to that
+      // remaining budget — the full interval is NOT used once a ceiling applies.
+      const { delay } = computeHistoryJob(page, 'user', T0, T0 + 60_000);
+      expect(delay).toBe(IDLE_MAX_WAIT_USER - 60_000);
+    });
+
+    it('never waits longer than the max-wait budget from the burst start', () => {
+      // A store arriving right at the ceiling → delay 0 (fire promptly).
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('past the ceiling never returns a negative delay', () => {
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER + 5 * 60_000,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('the agent ceiling is shorter than the user ceiling', () => {
+      expect(IDLE_MAX_WAIT_AGENT).toBeLessThan(IDLE_MAX_WAIT_USER);
+      const { delay } = computeHistoryJob(
+        page,
+        'agent',
+        T0,
+        T0 + IDLE_MAX_WAIT_AGENT,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('without a burstStart there is no ceiling (backward-compatible)', () => {
+      expect(computeHistoryJob(page, 'user').delay).toBe(IDLE_INTERVAL_USER);
+      expect(computeHistoryJob(page, 'agent').delay).toBe(IDLE_INTERVAL_AGENT);
+    });
+  });
 });
 
 describe('resolveSource (truth table)', () => {

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

@@ -40,11 +40,12 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
   let pageHistoryRepo: {
     saveHistory: jest.Mock;
     findPageLastHistory: jest.Mock;
+    updateHistoryKind: jest.Mock;
   };
   let aiQueue: { add: jest.Mock };
-  let historyQueue: { add: jest.Mock };
+  let historyQueue: { add: jest.Mock; remove: jest.Mock };
   let notificationQueue: { add: jest.Mock };
-  let collabHistory: { addContributors: jest.Mock };
+  let collabHistory: { addContributors: jest.Mock; popContributors: jest.Mock };
   let transclusionService: {
     syncPageTransclusions: jest.Mock;
     syncPageReferences: jest.Mock;
@@ -93,13 +94,22 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     pageHistoryRepo = {
       saveHistory: jest.fn().mockImplementation(async () => {
         callOrder.push('saveHistory');
+        return { id: 'history-1' };
       }),
       findPageLastHistory: jest.fn().mockResolvedValue(null),
+      updateHistoryKind: jest.fn().mockResolvedValue(undefined),
     };
     aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    historyQueue = {
+      add: jest.fn().mockResolvedValue(undefined),
+      // #370 — enqueuePageHistory now removes any pending idle job before re-adding.
+      remove: jest.fn().mockResolvedValue(undefined),
+    };
     notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    collabHistory = { addContributors: jest.fn().mockResolvedValue(undefined) };
+    collabHistory = {
+      addContributors: jest.fn().mockResolvedValue(undefined),
+      popContributors: jest.fn().mockResolvedValue([]),
+    };
     transclusionService = {
       syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
       syncPageReferences: jest.fn().mockResolvedValue(undefined),
@@ -165,6 +175,50 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
   });
 
+  // #370 review round-1 SUGGESTION: the boundary was GENERALIZED from a
+  // user→agent special-case to ANY lastUpdatedSource transition. These pin the
+  // generalized behaviour it was rebuilt for.
+  describe('generalized boundary — any source transition', () => {
+    // Same persisted page but with an explicit prior source.
+    const pageWithPriorSource = (prior: string | null) => ({
+      ...persistedHumanPage('NEW CONTENT'),
+      lastUpdatedSource: prior,
+    });
+
+    it('agent→user transition fires the boundary (pins the prior agent revision)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('agent'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+      expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
+    });
+
+    it('git→user transition fires the boundary (git-sync overwrite is a source change)', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource('git'));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(callOrder).toEqual(['saveHistory', 'updatePage']);
+    });
+
+    it('a null prior source (first-ever edit) does NOT fire the boundary', async () => {
+      const document = ydocFor(doc('NEW CONTENT'));
+      pageRepo.findById.mockResolvedValue(pageWithPriorSource(null));
+
+      await ext.onStoreDocument(buildData(document, 'agent') as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageRepo.updatePage).toHaveBeenCalledTimes(1);
+    });
+  });
+
   it('idempotency: unchanged content → no updatePage, no history, no queues', async () => {
     // The Y.Doc content equals the persisted content deeply → early skip.
     // A Y.Doc round-trip normalizes attrs (e.g. paragraph indent), so derive
@@ -479,4 +533,231 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
     // Contributors keyed by the UUID so they match the PAGE_HISTORY job (page.id).
     expect(collabHistory.addContributors.mock.calls[0][0]).toBe(PAGE_ID);
   });
+
+  // #370 — explicit save-version (Cmd+S / agent save tool) over the stateless
+  // seam. The tier is derived from the SIGNED connection actor, the store path
+  // is reused, and promote-not-dup avoids duplicating heavy content rows.
+  describe('save-version (#370)', () => {
+    const emitSave = (document: any, actor: 'user' | 'agent') =>
+      ext.onStateless({
+        connection: {
+          readOnly: false,
+          context: { user: { id: USER_ID, name: 'Alice' }, actor },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+    // findById returns a page whose content already equals the live doc, so the
+    // store path is a no-op and we isolate the versioning decision.
+    const pageMatchingDoc = (document: any) => ({
+      ...persistedHumanPage('IGNORED'),
+      content: TiptapTransformer.fromYdoc(document, 'default'),
+    });
+
+    it('human save with no prior snapshot → writes a manual version + broadcasts', async () => {
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.saveHistory).toHaveBeenCalledTimes(1);
+      expect(pageHistoryRepo.saveHistory.mock.calls[0][1]).toEqual(
+        expect.objectContaining({ kind: 'manual' }),
+      );
+      // The pending idle autosnapshot is cancelled by the explicit version.
+      expect(historyQueue.remove).toHaveBeenCalledWith(PAGE_ID);
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({
+        type: 'version.saved',
+        kind: 'manual',
+        alreadySaved: false,
+      });
+    });
+
+    it('agent save derives kind=agent from the signed actor', async () => {
+      const document = ydocFor(doc('AGENT VERSION'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await emitSave(document, 'agent');
+
+      expect(pageHistoryRepo.saveHistory.mock.calls[pageHistoryRepo.saveHistory.mock.calls.length - 1][1]).toEqual(
+        expect.objectContaining({ kind: 'agent' }),
+      );
+    });
+
+    it('promote-not-dup: latest snapshot is an autosave with identical content → upgrades in place', async () => {
+      const document = ydocFor(doc('SAME'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'auto-1',
+        content: page.content,
+        kind: 'idle',
+      });
+
+      await emitSave(document, 'user');
+
+      // No heavy new content row — the existing autosave is promoted to manual.
+      expect(pageHistoryRepo.updateHistoryKind).toHaveBeenCalledWith(
+        'auto-1',
+        'manual',
+        expect.anything(),
+      );
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ historyId: 'auto-1', alreadySaved: false });
+    });
+
+    it('no-op when the latest snapshot is already a manual version of this content', async () => {
+      const document = ydocFor(doc('ALREADY SAVED'));
+      const page = pageMatchingDoc(document);
+      pageRepo.findById.mockResolvedValue(page);
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+        id: 'ver-1',
+        content: page.content,
+        kind: 'manual',
+      });
+
+      await emitSave(document, 'user');
+
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      const msg = JSON.parse(
+        (document as any).broadcastStateless.mock.calls[(document as any).broadcastStateless.mock.calls.length - 1][0],
+      );
+      expect(msg).toMatchObject({ alreadySaved: true, kind: 'manual' });
+    });
+
+    it('a read-only connection cannot save a version', async () => {
+      const document = ydocFor(doc('READER'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+
+      await ext.onStateless({
+        connection: {
+          readOnly: true,
+          context: { user: { id: USER_ID }, actor: 'user' },
+        } as any,
+        documentName: `page.${PAGE_ID}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+      expect(pageHistoryRepo.saveHistory).not.toHaveBeenCalled();
+      expect(pageHistoryRepo.updateHistoryKind).not.toHaveBeenCalled();
+    });
+
+    // #370 F8-twin — a COMMIT abort (serialization/deadlock/conn-drop) rejects
+    // OUTSIDE the tx callback, AFTER the destructive popContributors (SPOP) and
+    // saveHistory ran but the INSERT rolled back. onStateless has no retry, so
+    // the outer catch MUST re-add (SADD) the popped set or attribution is lost
+    // irrecoverably. MUTATION: drop the outer catch → addContributors is never
+    // called → this reddens.
+    it('restores popped contributors when the commit aborts after the callback', async () => {
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      // No matching snapshot → fresh version branch → pops contributors.
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+      collabHistory.popContributors.mockResolvedValue(['u1', 'u2']);
+
+      // A db whose commit REJECTS after the callback body resolved: the SPOP and
+      // saveHistory already ran, then the tx aborts. onStoreDocument's flush uses
+      // the same db but its content matches (no-op branch) and its own retry loop
+      // swallows the throw, so only the versioning tx exercises the restore.
+      const commitFailingDb = {
+        transaction: () => ({
+          execute: async (fn: (trx: any) => Promise<any>) => {
+            await fn(trxStub);
+            throw new Error('commit aborted (serialization_failure)');
+          },
+        }),
+      };
+      const ext2 = new PersistenceExtension(
+        pageRepo as any,
+        pageHistoryRepo as any,
+        commitFailingDb as any,
+        aiQueue as any,
+        historyQueue as any,
+        notificationQueue as any,
+        collabHistory as any,
+        transclusionService as any,
+      );
+      jest.spyOn(ext2['logger'], 'debug').mockImplementation(() => undefined);
+      jest.spyOn(ext2['logger'], 'warn').mockImplementation(() => undefined);
+      jest.spyOn(ext2['logger'], 'error').mockImplementation(() => undefined);
+
+      await expect(
+        ext2.onStateless({
+          connection: {
+            readOnly: false,
+            context: { user: { id: USER_ID, name: 'Alice' }, actor: 'user' },
+          } as any,
+          documentName: `page.${PAGE_ID}`,
+          document: document as any,
+          payload: JSON.stringify({ type: 'save-version' }),
+        } as any),
+      ).rejects.toThrow();
+
+      // Attribution preserved: the popped set is SADD-restored, keyed by the page
+      // UUID it was popped under.
+      expect(collabHistory.addContributors).toHaveBeenCalledWith(PAGE_ID, [
+        'u1',
+        'u2',
+      ]);
+    });
+
+    // #370 #260 — for a `page.<slugId>` document the idle job is armed under the
+    // page UUID (computeHistoryJob's jobId = page.id), so the supersede-remove
+    // must target page.id, not the raw slugId doc-name id, or it silently misses.
+    it('cancels the superseded idle job by the page UUID for a slugId doc', async () => {
+      const SLUG = 'slug-1'; // persistedHumanPage.slugId
+      const document = ydocFor(doc('VERSION ME'));
+      pageRepo.findById.mockResolvedValue(pageMatchingDoc(document));
+      pageHistoryRepo.findPageLastHistory.mockResolvedValue(null);
+
+      await ext.onStateless({
+        connection: {
+          readOnly: false,
+          context: { user: { id: USER_ID, name: 'Alice' }, actor: 'user' },
+        } as any,
+        documentName: `page.${SLUG}`,
+        document: document as any,
+        payload: JSON.stringify({ type: 'save-version' }),
+      } as any);
+
+      // remove() keyed by the UUID (the real jobId), never the slugId.
+      expect(historyQueue.remove).toHaveBeenCalledWith(PAGE_ID);
+      expect(historyQueue.remove).not.toHaveBeenCalledWith(SLUG);
+    });
+  });
+
+  // #370 — the in-memory idle-burst marker must be dropped on doc unload (like
+  // its sibling per-document maps) or it grows unbounded for every page that was
+  // edited but never manually saved. MUTATION: drop the afterUnloadDocument
+  // delete → the entry survives → this reddens.
+  describe('idleBurstStart housekeeping', () => {
+    it('afterUnloadDocument clears the idle-burst marker armed by a store', async () => {
+      const document = ydocFor(doc('EDIT'));
+      pageRepo.findById.mockResolvedValue(persistedHumanPage('EDIT'));
+
+      await ext.onStoreDocument(buildData(document, 'user') as any);
+
+      const map = ext['idleBurstStart'] as Map<string, number>;
+      // Keyed by documentName (buildData uses `page.${PAGE_ID}`).
+      expect(map.has(`page.${PAGE_ID}`)).toBe(true);
+
+      await ext.afterUnloadDocument({
+        documentName: `page.${PAGE_ID}`,
+      } as any);
+
+      expect(map.has(`page.${PAGE_ID}`)).toBe(false);
+    });
+  });
 });

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

@@ -37,9 +37,11 @@ import { Page } from '@docmost/db/types/entity.types';
 import { CollabHistoryService } from '../services/collab-history.service';
 import {
   EMBED_DEBOUNCE_MS,
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
+  PageHistoryKind,
 } from '../constants';
 import { TransclusionService } from '../../core/page/transclusion/transclusion.service';
 import {
@@ -56,6 +58,16 @@ import { hasTransclusionFamilyNodes } from '../../core/page/transclusion/utils/t
  */
 export const INTENTIONAL_CLEAR_MESSAGE_TYPE = 'intentional-clear';
 
+/**
+ * #370 — wire format of the client→server "save a version" signal. Sent by the
+ * human (Cmd+S / Save button) and by the agent's explicit save tool over the
+ * SAME stateless channel. The intentionality tier ('manual' vs 'agent') is
+ * derived SERVER-SIDE from the signed connection actor, never from this
+ * payload, so a version's type is unforgeable. The document is taken from the
+ * connection (not the payload), so the signal cannot be aimed at another page.
+ */
+export const SAVE_VERSION_MESSAGE_TYPE = 'save-version';
+
 /**
  * #251 — how long an intentional-clear signal stays "pending" before it is
  * ignored. The signal is set on the clearing keystroke but consumed by the
@@ -92,35 +104,39 @@ export function resolveSource(
 }
 
 /**
- * Compute the BullMQ job id + delay for a page-history snapshot job. Pure so
- * the data-loss-sensitive timing arithmetic is unit-testable; `now` is injected
- * (caller passes `Date.now()`) for determinism.
+ * #370 — compute the BullMQ job id + delay for a page's trailing idle-flush
+ * autosnapshot. Pure so the timing is unit-testable.
  *
- * - Agent edits: delay 0 and a source-keyed job id `${page.id}-agent`. The
- *   delay MUST stay 0 — the worker re-reads the page row at run time, so any
- *   delay risks reading content a later human edit has already overwritten
- *   (mis-tagged snapshot). 0 minimizes that window. The `-agent` suffix keeps
- *   the job from coalescing with the bare-page.id human job.
- * - Human edits: age-based debounce so rapid human edits coalesce into one
- *   snapshot; job id is the bare `page.id`.
- *
- * BullMQ forbids ':' in custom job ids (Redis key separator), so '-' is used;
- * page.id is a UUID, so `${page.id}-agent` cannot collide with a human job.
+ * Both humans and the agent now share ONE idle pipeline (the agent's old
+ * `delay=0` fast path is gone — intentional agent points arrive via the
+ * explicit save-version signal instead). The job id is the bare `page.id`, so a
+ * page has at most one pending idle job; the caller removes-and-re-adds it on
+ * every store to keep it debounced to the trailing edge of an edit burst. The
+ * window differs by source only: the agent flushes sooner than a human.
  */
 export function computeHistoryJob(
-  page: Pick<Page, 'id' | 'createdAt'>,
+  page: Pick<Page, 'id'>,
   source: string,
-  now: number,
+  // Epoch ms of the FIRST edit in the current burst (when the pending idle job
+  // was first armed). Used to enforce the max-wait ceiling so a continuous
+  // editing session cannot re-arm the trailing timer forever. `now` is injectable
+  // for tests; both default to a live clock / no ceiling when omitted.
+  burstStart?: number,
+  now: number = Date.now(),
 ): { jobId: string; delay: number } {
   const isAgent = source === 'agent';
-  const pageAge = now - new Date(page.createdAt).getTime();
-  const delay = isAgent
-    ? 0
-    : pageAge < HISTORY_FAST_THRESHOLD
-      ? HISTORY_FAST_INTERVAL
-      : HISTORY_INTERVAL;
-  const jobId = isAgent ? `${page.id}-agent` : page.id;
-  return { jobId, delay };
+  const interval = isAgent ? IDLE_INTERVAL_AGENT : IDLE_INTERVAL_USER;
+  const maxWait = isAgent ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+
+  let delay = interval;
+  if (burstStart !== undefined) {
+    // Time already elapsed since the burst's first edit; the snapshot must fire
+    // no later than `maxWait` after that, so shrink the trailing delay to the
+    // remaining budget (never negative, so BullMQ fires it promptly).
+    const remaining = burstStart + maxWait - now;
+    delay = Math.max(0, Math.min(interval, remaining));
+  }
+  return { jobId: page.id, delay };
 }
 
 @Injectable()
@@ -132,6 +148,28 @@ export class PersistenceExtension implements Extension {
   // coalescing window" per document and OR it across all edits in the window,
   // so the snapshot is marked 'agent' regardless of who wrote last.
   private agentTouched: Map<string, boolean> = new Map();
+  // #370 — epoch ms of the FIRST edit in the current idle-flush burst. Keyed by
+  // documentName (like its sibling per-document maps above), NOT by page.id, so
+  // it can be cleaned in afterUnloadDocument alongside `contributors` /
+  // `agentTouched` / `intentionalClear` when the doc unloads — otherwise any page
+  // that was edited but never manually saved (the common case) would keep its
+  // entry forever and the Map would grow unbounded in this long-lived process.
+  // Set when the pending idle job is first armed (empty entry), read to enforce
+  // the max-wait ceiling in computeHistoryJob, and cleared on doc unload or when
+  // a manual save cancels the idle job so the next burst starts a fresh window.
+  //
+  // Single-process assumption (like `contributors` / `agentTouched` above): this
+  // lives only in THIS collab process's memory. A restart, or a page's ownership
+  // moving to another node, loses the burst-start marker. Consequence: a burst
+  // that spans the restart looks like a fresh burst to the surviving process, so
+  // its max-wait ceiling is re-anchored to the first post-restart edit — a single
+  // continuous session straddling a restart can therefore wait up to ~2× the cap
+  // for its idle snapshot (once for the lost pre-restart window, once for the new
+  // one). Bounded and benign (it only DELAYS a safety-net autosnapshot; manual
+  // saves are unaffected and the next quiet period always flushes), but the
+  // assumption and its consequence are recorded here so no one mistakes the
+  // in-memory marker for a durable, cross-process guarantee.
+  private idleBurstStart: Map<string, number> = new Map();
   // #251 — per-document "intentional clear pending" flags. Keyed by
   // documentName, value = expiry timestamp (ms). Set by onStateless when the
   // client reports a deliberate clear; consumed once by the next
@@ -363,20 +401,19 @@ export class PersistenceExtension implements Extension {
             //this.logger.debug('Contributors error:' + err?.['message']);
           }
 
-          // Approach A — boundary snapshot before the agent's first edit.
-          // When this store is the agent's and the page's currently persisted
-          // state was authored by a human, pin that human state as its own
-          // history version BEFORE the agent overwrites it. `page` still holds
-          // the OLD content/provenance here, so saveHistory(page) captures the
-          // pre-agent state tagged 'user'. The agent's new content is
-          // snapshotted later by the debounced PAGE_HISTORY job ('agent'). Skip
-          // if the prior state is already agent-authored (boundary already
-          // pinned on the user->agent transition), if the page is effectively
-          // empty, or if the latest existing snapshot already equals this human
-          // state (avoid duplicates).
+          // #370 — boundary snapshot on ANY source transition. When the store
+          // flips the page's provenance (user↔agent↔git), pin the OUTGOING
+          // state as its own history version BEFORE the incoming source
+          // overwrites it. `page` still holds the OLD content/provenance here,
+          // so saveHistory(page) captures the pre-transition state tagged with
+          // its own source, kind='boundary'. The incoming content is snapshotted
+          // later by the debounced idle job. Skip if the page is effectively
+          // empty or if the latest existing snapshot already equals this state
+          // (the shared isDeepStrictEqual gate — avoids duplicates). Generalizing
+          // beyond the old user→agent special-case also covers git-sync for free.
           if (
-            lastUpdatedSource === 'agent' &&
-            page.lastUpdatedSource !== 'agent'
+            page.lastUpdatedSource &&
+            page.lastUpdatedSource !== lastUpdatedSource
           ) {
             // pageHistory.pageId is uuid-typed; use page.id (never the doc-name
             // slugId) so a `page.<slugId>` doc cannot throw 22P02 here (#260).
@@ -384,15 +421,13 @@ export class PersistenceExtension implements Extension {
               page.id,
               { includeContent: true, trx },
             );
-            const humanBaselineMissing =
+            const baselineMissing =
               !lastHistory ||
               !isDeepStrictEqual(lastHistory.content, page.content);
-            if (
-              !isEmptyParagraphDoc(page.content as any) &&
-              humanBaselineMissing
-            ) {
+            if (!isEmptyParagraphDoc(page.content as any) && baselineMissing) {
               await this.pageHistoryRepo.saveHistory(page, {
                 contributorIds: page.contributorIds ?? undefined,
+                kind: 'boundary',
                 trx,
               });
             }
@@ -522,7 +557,7 @@ export class PersistenceExtension implements Extension {
         { jobId: `embed-${page.id}`, delay: EMBED_DEBOUNCE_MS },
       );
 
-      await this.enqueuePageHistory(page, lastUpdatedSource);
+      await this.enqueuePageHistory(page, documentName, lastUpdatedSource);
     }
 
     // #402 — report the serialized size for the store histogram's size_bucket.
@@ -554,6 +589,14 @@ export class PersistenceExtension implements Extension {
       return; // unrelated / malformed stateless message
     }
 
+    // #370 — explicit "save a version" (human Cmd+S / agent save tool). Edit
+    // rights are already enforced by the readOnly reject above (a reader can't
+    // create a version), exactly as intentional-clear requires.
+    if (message?.type === SAVE_VERSION_MESSAGE_TYPE) {
+      await this.handleSaveVersion(data);
+      return;
+    }
+
     if (message?.type !== INTENTIONAL_CLEAR_MESSAGE_TYPE) return;
 
     this.intentionalClear.set(
@@ -562,6 +605,160 @@ export class PersistenceExtension implements Extension {
     );
   }
 
+  /**
+   * #370 — persist an intentional version from the live in-memory ydoc.
+   *
+   * One stateless path serves BOTH the human and the agent; the tier is derived
+   * SERVER-SIDE from the signed connection actor ('agent' → 'agent', anything
+   * else → 'manual'), so the version type cannot be spoofed by the client. We
+   * take the fresh ydoc from the collab process memory and run it through the
+   * EXISTING store path first (so pages.content/ydoc reflect the exact content
+   * being versioned — a REST endpoint would race the up-to-10s-stale page row),
+   * then snapshot it into page_history with the intentional kind.
+   *
+   * Promote-not-dup: if the latest history row already holds this exact content
+   * and it is an autosave (idle/boundary/legacy-null), upgrade its kind in place
+   * instead of duplicating a heavy content row; if it is already 'manual', it is
+   * a no-op (the client shows an "already saved" toast). Otherwise a fresh
+   * version row is written, popping the aggregated contributors from Redis.
+   */
+  private async handleSaveVersion(data: onStatelessPayload): Promise<void> {
+    const { connection, document, documentName } = data;
+    const context = connection?.context;
+    const pageId = getPageId(documentName);
+    // Unforgeable: 'agent' only for a signed agent connection, else 'manual'.
+    const kind: PageHistoryKind =
+      context?.actor === 'agent' ? 'agent' : 'manual';
+
+    // Flush the live ydoc through the normal store path so the page row + ydoc
+    // hold exactly what we are about to version (also fires the idle enqueue we
+    // supersede below, plus any source-transition boundary). onStoreDocument
+    // only needs document/documentName/context.
+    await this.onStoreDocument({
+      document,
+      documentName,
+      context,
+    } as onStoreDocumentPayload);
+
+    let result:
+      | { historyId: string; kind: PageHistoryKind; alreadySaved: boolean }
+      | undefined;
+
+    // #370 F8-twin — the contributor set popped from Redis (destructive SPOP)
+    // must be restored if the version row does not durably land. The inner
+    // try/catch below only covers a throw INSIDE the callback; but executeTx
+    // COMMITS after the callback, so a commit-abort (serialization/deadlock/
+    // connection drop — the transient class the epic retries in the processor)
+    // rejects OUTSIDE the callback, after saveHistory already ran and the SPOP
+    // already happened, while the INSERT rolls back. onStateless does NOT retry,
+    // so an unrestored pop is a one-shot irrecoverable attribution loss (the
+    // processor got exactly this fix: poppedForRestore + an outer catch). We
+    // track the popped set here (keyed by the page UUID it was popped by — never
+    // the doc-name id, which may be a slugId, #260) and restore it in the outer
+    // catch. addContributors is an idempotent Redis SADD, so a double-restore is
+    // harmless. versionedPageId is also reused below to remove the superseded
+    // idle job by its real jobId (page.id).
+    let poppedForRestore: string[] = [];
+    let versionedPageId: string | undefined;
+
+    try {
+      await executeTx(this.db, async (trx) => {
+        const page = await this.pageRepo.findById(pageId, {
+          withLock: true,
+          includeContent: true,
+          trx,
+        });
+        if (!page) return;
+        versionedPageId = page.id;
+        // Never version an effectively-empty page (mirrors the processor's
+        // first-history guard); there is nothing intentional to pin.
+        if (isEmptyParagraphDoc(page.content as any)) return;
+
+        const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+          page.id,
+          { includeContent: true, trx },
+        );
+
+        if (
+          lastHistory &&
+          isDeepStrictEqual(lastHistory.content, page.content)
+        ) {
+          // Content is already snapshotted. Promote-not-dup.
+          if (lastHistory.kind === 'manual') {
+            result = {
+              historyId: lastHistory.id,
+              kind: 'manual',
+              alreadySaved: true,
+            };
+            return;
+          }
+          await this.pageHistoryRepo.updateHistoryKind(
+            lastHistory.id,
+            kind,
+            trx,
+          );
+          result = { historyId: lastHistory.id, kind, alreadySaved: false };
+          return;
+        }
+
+        // Fresh version row. Pop the contributors aggregated since the last
+        // snapshot (SPOP); restore them if the write fails so they aren't lost.
+        const contributorIds = await this.collabHistory.popContributors(
+          page.id,
+        );
+        poppedForRestore = contributorIds;
+        try {
+          const saved = await this.pageHistoryRepo.saveHistory(page, {
+            contributorIds,
+            kind,
+            trx,
+          });
+          result = { historyId: saved.id, kind, alreadySaved: false };
+        } catch (err) {
+          await this.collabHistory.addContributors(page.id, contributorIds);
+          poppedForRestore = [];
+          throw err;
+        }
+      });
+    } catch (err) {
+      // A throw here means the tx did NOT commit (callback threw, or the commit
+      // itself failed and rolled back). If we popped contributors and the inner
+      // catch did not already restore them, restore now so attribution is not
+      // lost — onStateless has no retry to recover it. Restore by the page UUID
+      // the pop was keyed under (versionedPageId is always set before the pop).
+      if (poppedForRestore.length && versionedPageId) {
+        await this.collabHistory.addContributors(
+          versionedPageId,
+          poppedForRestore,
+        );
+      }
+      throw err;
+    }
+
+    // Housekeeping: this explicit version supersedes the page's pending idle
+    // autosnapshot, so cancel it and end the current idle burst so the next edit
+    // starts a fresh max-wait window. Remove the idle job by its REAL jobId
+    // (page.id UUID — computeHistoryJob arms it under page.id), not the raw
+    // doc-name id which may be a slugId for a `page.<slugId>` doc (#260), or the
+    // remove silently misses. The burst marker is keyed by documentName (like its
+    // sibling per-document maps), and is also cleaned in afterUnloadDocument.
+    if (versionedPageId) {
+      await this.historyQueue.remove(versionedPageId).catch(() => undefined);
+    }
+    this.idleBurstStart.delete(documentName);
+
+    if (result) {
+      document.broadcastStateless(
+        JSON.stringify({
+          type: 'version.saved',
+          historyId: result.historyId,
+          kind: result.kind,
+          alreadySaved: result.alreadySaved,
+        }),
+      );
+    }
+  }
+
   async onChange(data: onChangePayload) {
     const documentName = data.documentName;
     const userId = data.context?.user?.id;
@@ -586,6 +783,10 @@ export class PersistenceExtension implements Extension {
     this.contributors.delete(documentName);
     this.agentTouched.delete(documentName);
     this.intentionalClear.delete(documentName);
+    // #370 — drop the idle-burst marker with the other per-document maps so it
+    // cannot accumulate across the process lifetime for never-manually-saved
+    // pages. The pending idle job (if any) is a self-expiring BullMQ delayed job.
+    this.idleBurstStart.delete(documentName);
   }
 
   private consumeContributors(documentName: string): string[] {
@@ -617,19 +818,80 @@ export class PersistenceExtension implements Extension {
 
   private async enqueuePageHistory(
     page: Page,
+    documentName: string,
     lastUpdatedSource: string,
   ): Promise<void> {
-    // Job id + delay arithmetic lives in the pure `computeHistoryJob` (see its
-    // doc comment for the agent-delay-0 / age-based-debounce invariants).
+    // #370 — trailing idle debounce with a max-wait ceiling. One pending idle
+    // job per page (jobId = page.id); on every store we remove the pending
+    // delayed job and re-add it, so the snapshot lands `delay` after edits go
+    // quiet rather than once per store (precedent: workspace.service.ts).
+    // remove() on a delayed job simply deletes it (0 if absent, no throw); if the
+    // job is already ACTIVE and the remove is a no-op, the add still de-dups and
+    // the processor's isDeepStrictEqual gate collapses the duplicate content.
+    //
+    // The FIRST arm of a burst records `burstStart`; computeHistoryJob shrinks
+    // the delay to the remaining max-wait budget from that point, so a continuous
+    // session cannot re-arm the trailing timer forever and starve the snapshot.
+    // A burst marker older than THIS TIER's max-wait means the previous idle job
+    // has already fired — start a fresh window instead of firing immediately on
+    // the next edit. Must use the SAME source-specific max-wait computeHistoryJob
+    // uses (agent 5m / user 10m): a hardcoded USER ceiling would leave an agent
+    // burst's marker stale for 5..10m, forcing delay=0 on every store in that
+    // window and writing one idle row per store — exactly the per-store bloat the
+    // debounce exists to prevent, on the continuous-agent path.
+    const maxWait =
+      lastUpdatedSource === 'agent' ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+    const now = Date.now();
+    // Keyed by documentName (see the map declaration) so afterUnloadDocument can
+    // clean it; the queue jobId stays page.id (computeHistoryJob) as required.
+    let burstStart = this.idleBurstStart.get(documentName);
+    if (burstStart === undefined || now - burstStart >= maxWait) {
+      burstStart = now;
+      this.idleBurstStart.set(documentName, burstStart);
+    }
+
     const { jobId, delay } = computeHistoryJob(
       page,
       lastUpdatedSource,
-      Date.now(),
+      burstStart,
+      now,
     );
 
+    // remove-then-add trailing-debounce idiom, and its ONE race. We delete the
+    // pending delayed job and re-add it under the same jobId so the timer resets
+    // to the trailing edge of the burst. The race is the small window between
+    // these two awaits: if the delayed job's `delay` elapses in that gap it goes
+    // ACTIVE, and then:
+    //   - remove() on an active/locked job is a no-op (BullMQ won't yank a job a
+    //     worker holds), and our `.catch(() => undefined)` swallows that too; and
+    //   - add() with a jobId that already exists (the now-active job's id) is
+    //     DROPPED by BullMQ — a duplicate add is a no-op.
+    // So this store fails to re-arm the trailing job: the just-fired snapshot
+    // captured content up to the moment it went active, and THIS edit is left
+    // without a pending trailing job. It is bounded and self-healing — the NEXT
+    // store re-arms a fresh delayed job (the id is free again once the active job
+    // completes / removeOnComplete frees it), and the processor's
+    // isDeepStrictEqual gate collapses any content-identical duplicate. The only
+    // uncovered case is when the racing store was the LAST in the session: the
+    // tail edits made after the job went active get NO trailing snapshot until
+    // the next edit re-arms one. That is an acceptable safety-net gap (a manual
+    // Save, a source-transition boundary, or simply the next edit all still cover
+    // it), which is why the reviewer accepts documenting it here rather than
+    // adding a post-add "did the add actually arm a job?" re-check.
+    //
+    // NOTE — do NOT "unify" this with the neighbouring embed-debounce idiom
+    // (aiQueue.add of PAGE_CONTENT_UPDATED above): that one uses a STABLE jobId
+    // and NO remove(), relying purely on BullMQ coalescing a repeated add under
+    // the same id, because a re-embed only needs to eventually run once on the
+    // latest content and re-anchoring its delay on every keystroke is undesirable.
+    // THIS idiom deliberately removes-then-adds precisely to PUSH the delay back
+    // to the trailing edge on every store (a true debounce), which coalescing
+    // alone cannot do. Collapsing them would silently change the history cadence.
+    await this.historyQueue.remove(jobId).catch(() => undefined);
+
     await this.historyQueue.add(
       QueueJob.PAGE_HISTORY,
-      { pageId: page.id } as IPageHistoryJob,
+      { pageId: page.id, kind: 'idle' } as IPageHistoryJob,
       { jobId, delay },
     );
   }

apps/server/src/collaboration/processors/history.processor.spec.ts

@@ -66,6 +66,15 @@ describe('HistoryProcessor.process', () => {
     notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
     generalQueue = { add: jest.fn().mockResolvedValue(undefined) };
 
+    // #370 F3 — the processor now serializes its find+save under a page-row lock
+    // via executeTx. A db whose transaction().execute(fn) runs fn with a trx stub
+    // drives the real executeTx() helper without a database.
+    const db = {
+      transaction: () => ({
+        execute: (fn: (trx: any) => Promise<any>) => fn({ __trx: true }),
+      }),
+    };
+
     // WorkerHost's constructor reads `this.worker`; passing repos positionally
     // matches the constructor and avoids the Nest DI container.
     proc = new HistoryProcessor(
@@ -73,6 +82,7 @@ describe('HistoryProcessor.process', () => {
       pageRepo as any,
       collabHistory as any,
       watcherService as any,
+      db as any,
       notificationQueue as any,
       generalQueue as any,
     );
@@ -126,15 +136,26 @@ describe('HistoryProcessor.process', () => {
     await proc.process(buildJob());
 
     expect(collabHistory.popContributors).toHaveBeenCalledWith(PAGE_ID);
+    // #370 F3/F9 — the snapshot decision runs under a page-row lock. Pin the lock
+    // structurally so a refactor that drops withLock/trx (silently reintroducing
+    // the TOCTOU double-insert) turns this red. The tx stub is { __trx: true }.
+    expect(pageRepo.findById).toHaveBeenCalledWith(
+      PAGE_ID,
+      expect.objectContaining({ withLock: true, trx: { __trx: true } }),
+    );
+    // #370 F7 — addPageWatchers MUST receive the trx, or its FK-check runs on a
+    // separate connection and self-deadlocks against our FOR UPDATE. Asserting
+    // the trx arg here is exactly what would have caught that regression.
     expect(watcherService.addPageWatchers).toHaveBeenCalledWith(
       ['u1', 'u2'],
       PAGE_ID,
       SPACE_ID,
       WORKSPACE_ID,
+      { __trx: true },
     );
     expect(pageHistoryRepo.saveHistory).toHaveBeenCalledWith(
       expect.objectContaining({ id: PAGE_ID }),
-      { contributorIds: ['u1', 'u2'] },
+      { contributorIds: ['u1', 'u2'], kind: 'idle', trx: { __trx: true } },
     );
     expect(generalQueue.add).toHaveBeenCalledWith(
       QueueJob.PAGE_BACKLINKS,
@@ -186,6 +207,48 @@ describe('HistoryProcessor.process', () => {
     ]);
   });
 
+  it('COMMIT failure (throw outside the tx callback) → contributors RESTORED', async () => {
+    // #370 F8 — a commit-time failure throws OUTSIDE the callback, so the inner
+    // try/catch does not run; the outer catch must restore the popped set (else a
+    // BullMQ retry writes an unattributed version). Use a db whose execute() runs
+    // the callback THEN throws, simulating a commit abort.
+    pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+      content: { type: 'doc', content: [] },
+    });
+    const commitFail = {
+      transaction: () => ({
+        execute: async (fn: (trx: any) => Promise<any>) => {
+          await fn({ __trx: true }); // callback succeeds (saveHistory ok)
+          throw new Error('commit aborted'); // ...but the COMMIT fails
+        },
+      }),
+    };
+    const procCommitFail = new HistoryProcessor(
+      pageHistoryRepo as any,
+      pageRepo as any,
+      collabHistory as any,
+      watcherService as any,
+      commitFail as any,
+      notificationQueue as any,
+      generalQueue as any,
+    );
+    jest
+      .spyOn(procCommitFail['logger'], 'error')
+      .mockImplementation(() => undefined);
+
+    await expect(procCommitFail.process(buildJob())).rejects.toThrow(
+      'commit aborted',
+    );
+    // The inner catch did NOT run (save succeeded), so only the outer catch can
+    // restore — assert it did.
+    expect(collabHistory.addContributors).toHaveBeenCalledWith(PAGE_ID, [
+      'u1',
+      'u2',
+    ]);
+    // And the post-snapshot queue work must NOT have run (we rethrew).
+    expect(generalQueue.add).not.toHaveBeenCalled();
+  });
+
   it('backlinks + notification queue failures are swallowed (history still committed)', async () => {
     pageHistoryRepo.findPageLastHistory.mockResolvedValue({
       content: { type: 'doc', content: [] },

apps/server/src/collaboration/processors/history.processor.ts

@@ -19,6 +19,9 @@ import { isDeepStrictEqual } from 'node:util';
 import { CollabHistoryService } from '../services/collab-history.service';
 import { WatcherService } from '../../core/watcher/watcher.service';
 import { isEmptyParagraphDoc } from '../collaboration.util';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';
 
 @Processor(QueueName.HISTORY_QUEUE)
 export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
@@ -29,6 +32,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
     private readonly pageRepo: PageRepo,
     private readonly collabHistory: CollabHistoryService,
     private readonly watcherService: WatcherService,
+    @InjectKysely() private readonly db: KyselyDB,
     @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
     @InjectQueue(QueueName.GENERAL_QUEUE) private generalQueue: Queue,
   ) {
@@ -41,6 +45,9 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
     try {
       const { pageId } = job.data;
 
+      // Read the page WITHOUT a lock first, only to bail early on the two cheap
+      // no-write cases (page gone / empty first snapshot) without opening a
+      // transaction. The authoritative check-then-write happens locked below.
       const page = await this.pageRepo.findById(pageId, {
         includeContent: true,
       });
@@ -51,40 +58,109 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
         return;
       }
 
-      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
-        pageId,
-        { includeContent: true },
-      );
+      // #370 F3 — the snapshot decision (findPageLastHistory → saveHistory) must
+      // be serialized against manual-save/boundary writers, which run under a
+      // page-row lock in onStoreDocument. Without it, this processor and a
+      // concurrent manual-save each read the same lastHistory (MVCC), both see
+      // content != lastHistory, and both insert — producing two page_history rows
+      // with IDENTICAL content (one 'idle', one 'manual'), defeating
+      // promote-not-dup and the version-vs-autosave split. Taking the same
+      // page-row lock makes the second writer observe the first's committed row so
+      // the isDeepStrictEqual gate collapses the duplicate. Only the read+write
+      // is transacted; the post-snapshot queue work stays outside.
+      let contributorIds: string[] = [];
+      let snapshotWritten = false;
+      let lastHistoryContent: unknown;
+      // #370 F8 — the contributor set popped from Redis (destructive SPOP) must be
+      // restored if the snapshot does not durably land. The inner try/catch only
+      // covers a throw INSIDE the callback; a COMMIT failure (connection drop,
+      // serialization/deadlock abort on commit — the transient class the epic
+      // already retries) throws OUTSIDE it, rolling the snapshot back while the
+      // pop is already gone. We track the popped set here and restore it in the
+      // outer catch so a BullMQ retry re-attributes the version. addContributors
+      // is an idempotent Redis SADD, so a double-restore is harmless.
+      let poppedForRestore: string[] = [];
 
-      if (!lastHistory && isEmptyParagraphDoc(page.content as any)) {
-        this.logger.debug(
-          `Skipping first history for page ${pageId}: empty content`,
-        );
-        await this.collabHistory.clearContributors(pageId);
+      try {
+        await executeTx(this.db, async (trx) => {
+          const lockedPage = await this.pageRepo.findById(pageId, {
+            includeContent: true,
+            withLock: true,
+            trx,
+          });
+          if (!lockedPage) return;
+
+          const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+            pageId,
+            { includeContent: true, trx },
+          );
+          lastHistoryContent = lastHistory?.content;
+
+          if (!lastHistory && isEmptyParagraphDoc(lockedPage.content as any)) {
+            this.logger.debug(
+              `Skipping first history for page ${pageId}: empty content`,
+            );
+            return;
+          }
+
+          if (
+            lastHistory &&
+            isDeepStrictEqual(lastHistory.content, lockedPage.content)
+          ) {
+            return; // already snapshotted at this content — nothing to write
+          }
+
+          contributorIds = await this.collabHistory.popContributors(pageId);
+          poppedForRestore = contributorIds;
+          try {
+            // Pass `trx` so the watcher insert's FK check (FOR KEY SHARE on
+            // pages[pageId]) runs on the SAME connection that already holds the
+            // FOR UPDATE lock from findById — otherwise it takes the FK lock on a
+            // separate pool connection and self-deadlocks against our own tx.
+            await this.watcherService.addPageWatchers(
+              contributorIds,
+              pageId,
+              lockedPage.spaceId,
+              lockedPage.workspaceId,
+              trx,
+            );
+
+            // #370 — every job on this queue is a trailing idle-flush autosnapshot.
+            await this.pageHistoryRepo.saveHistory(lockedPage, {
+              contributorIds,
+              kind: job.data.kind ?? 'idle',
+              trx,
+            });
+            snapshotWritten = true;
+            this.logger.debug(`History created for page: ${pageId}`);
+          } catch (err) {
+            await this.collabHistory.addContributors(pageId, contributorIds);
+            poppedForRestore = [];
+            throw err;
+          }
+        });
+      } catch (err) {
+        // A throw here means the tx did NOT commit (callback threw, or the commit
+        // itself failed and rolled back). If we popped contributors and the inner
+        // catch did not already restore them, restore now so the retry keeps
+        // attribution. snapshotWritten is irrelevant: it is set before commit, so
+        // it can be true even when the commit rolled the snapshot back.
+        if (poppedForRestore.length) {
+          await this.collabHistory.addContributors(pageId, poppedForRestore);
+        }
+        throw err;
+      }
+
+      // No snapshot written (page vanished / empty-first / unchanged content) →
+      // clear the contributor set for the skip cases and stop.
+      if (!snapshotWritten) {
+        if (!lastHistoryContent && isEmptyParagraphDoc(page.content as any)) {
+          await this.collabHistory.clearContributors(pageId);
+        }
         return;
       }
 
-      if (
-        !lastHistory ||
-        !isDeepStrictEqual(lastHistory.content, page.content)
-      ) {
-        const contributorIds = await this.collabHistory.popContributors(pageId);
-
-        try {
-          await this.watcherService.addPageWatchers(
-            contributorIds,
-            pageId,
-            page.spaceId,
-            page.workspaceId,
-          );
-
-          await this.pageHistoryRepo.saveHistory(page, { contributorIds });
-          this.logger.debug(`History created for page: ${pageId}`);
-        } catch (err) {
-          await this.collabHistory.addContributors(pageId, contributorIds);
-          throw err;
-        }
-
+      {
         const mentions = extractMentions(page.content);
         const pageMentions = extractPageMentions(mentions);
         const internalLinkSlugIds = extractInternalLinkSlugIds(page.content);
@@ -102,7 +178,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
             );
           });
 
-        if (contributorIds.length > 0 && lastHistory?.content) {
+        if (contributorIds.length > 0 && lastHistoryContent) {
           await this.notificationQueue
             .add(QueueJob.PAGE_UPDATED, {
               pageId,

apps/server/src/collaboration/yjs.util.spec.ts

@@ -529,4 +529,107 @@ describe('replaceYjsMarkedText', () => {
     expect(result).toEqual({ applied: false, currentText: 'abcdef' });
     expect(text.toDelta()).toEqual(before);
   });
+
+  // #496: apply must NOT silently strip the replaced run's inline formatting.
+  // Build a paragraph and format the marked range with extra marks, then assert
+  // the replacement carries them.
+  function buildFormatted(
+    runs: Array<{ text: string; attrs?: Record<string, any> }>,
+  ): { fragment: Y.XmlFragment; text: Y.XmlText } {
+    const ydoc = new Y.Doc();
+    const fragment = ydoc.getXmlFragment('default');
+    const para = new Y.XmlElement('paragraph');
+    fragment.insert(0, [para]);
+    const text = new Y.XmlText();
+    para.insert(0, [text]);
+    text.insert(0, runs.map((r) => r.text).join(''));
+    let offset = 0;
+    for (const run of runs) {
+      if (run.attrs) text.format(offset, run.text.length, run.attrs);
+      offset += run.text.length;
+    }
+    return { fragment, text };
+  }
+
+  it('preserves the original run formatting (bold + link) on the replacement', () => {
+    const { fragment, text } = buildFormatted([
+      { text: 'see ' },
+      {
+        text: 'old',
+        attrs: {
+          comment: { commentId: 'c1', resolved: false },
+          bold: true,
+          link: { href: 'https://x.test' },
+        },
+      },
+      { text: ' end' },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'old', 'new');
+
+    expect(result).toEqual({ applied: true, currentText: 'new' });
+    // The comment anchor AND the bold/link marks survive the delete+insert.
+    expect(text.toDelta()).toEqual([
+      { insert: 'see ' },
+      {
+        insert: 'new',
+        attributes: {
+          comment: { commentId: 'c1', resolved: false },
+          bold: true,
+          link: { href: 'https://x.test' },
+        },
+      },
+      { insert: ' end' },
+    ]);
+  });
+
+  it('mixed formatting under the mark: replacement takes the DOMINANT (longest) run, NOT the leading one', () => {
+    // Leading run is SHORT + plain ("x", 1 char); the following run is LONGER +
+    // bold ("bolded", 6 chars), same commentId. The longest run is deliberately
+    // NOT first: a "first-wins" pick would carry plain (no bold), so asserting
+    // bold on the result only holds if the code genuinely selects the LONGEST run.
+    const { fragment, text } = buildFormatted([
+      { text: 'x', attrs: { comment: { commentId: 'c1', resolved: false } } },
+      {
+        text: 'bolded',
+        attrs: { comment: { commentId: 'c1', resolved: false }, bold: true },
+      },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'xbolded', 'Z');
+
+    expect(result).toEqual({ applied: true, currentText: 'Z' });
+    expect(text.toDelta()).toEqual([
+      {
+        insert: 'Z',
+        attributes: { comment: { commentId: 'c1', resolved: false }, bold: true },
+      },
+    ]);
+  });
+
+  it('mixed formatting under the mark: on a length tie the FIRST run wins', () => {
+    // Two equal-length runs (2 chars each) with different formatting, same
+    // commentId. The reduce keeps the accumulator on a tie, so the FIRST run
+    // (italic) prevails over the later bold one.
+    const { fragment, text } = buildFormatted([
+      {
+        text: 'AA',
+        attrs: { comment: { commentId: 'c1', resolved: false }, italic: true },
+      },
+      {
+        text: 'BB',
+        attrs: { comment: { commentId: 'c1', resolved: false }, bold: true },
+      },
+    ]);
+
+    const result = replaceYjsMarkedText(fragment, 'c1', 'AABB', 'Z');
+
+    expect(result).toEqual({ applied: true, currentText: 'Z' });
+    expect(text.toDelta()).toEqual([
+      {
+        insert: 'Z',
+        attributes: { comment: { commentId: 'c1', resolved: false }, italic: true },
+      },
+    ]);
+  });
 });

apps/server/src/collaboration/yjs.util.ts

@@ -145,6 +145,10 @@ type MarkedSegment = {
   length: number;
   text: string;
   markAttrs: Record<string, any>;
+  // The FULL attribute set of this delta run — the `comment` mark plus any
+  // inline formatting (bold/italic/code/link/…). Captured so apply can carry the
+  // original run's formatting onto the replacement instead of dropping it.
+  attributes: Record<string, any>;
 };
 
 /**
@@ -202,6 +206,7 @@ export function replaceYjsMarkedText(
             length,
             text: insert,
             markAttrs: markAttr,
+            attributes,
           });
         }
         offset += length;
@@ -251,15 +256,25 @@ export function replaceYjsMarkedText(
     return { applied: false, currentText: joinedText };
   }
 
-  // 3. All guards passed: delete the marked run and re-insert newText with the
-  // same comment attributes at the same offset. Atomic within the caller's
-  // transaction.
+  // 3. All guards passed: delete the marked run and re-insert newText at the
+  // same offset. Atomic within the caller's transaction.
   const start = segments[0].offset;
   const len = segments.reduce((sum, s) => sum + s.length, 0);
-  const markAttrs = segments[0].markAttrs;
+
+  // Carry the ORIGINAL run's formatting onto the replacement (#496): inserting
+  // with only the `comment` mark silently dropped bold/italic/code/link of the
+  // replaced text. Yjs applies one flat attribute set to the whole insert, so
+  // when the marked run mixes formatting we pick the DOMINANT segment (the one
+  // covering the most characters) and apply its attributes — a v1 that preserves
+  // the common single-format case exactly and, for a mixed run, keeps the
+  // prevailing style rather than losing all of it. `attributes` already carries
+  // the `comment` mark (every collected segment is filtered on it above), so the
+  // anchor is preserved by copying the run's attribute set verbatim.
+  const dominant = segments.reduce((a, b) => (b.length > a.length ? b : a));
+  const insertAttrs = { ...dominant.attributes };
 
   node.delete(start, len);
-  node.insert(start, newText, { comment: markAttrs });
+  node.insert(start, newText, insertAttrs);
 
   return { applied: true, currentText: newText };
 }

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

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

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

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

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

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

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

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

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

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

apps/server/src/core/ai-chat/ai-chat.parts-resilience.spec.ts

@@ -0,0 +1,142 @@
+// #489 — client-parts validation + resilient history conversion.
+//
+// These unit tests exercise the two exported helpers against the REAL
+// `convertToModelMessages` from `ai` (NOT a mock): a genuinely malformed part
+// (a `null` element inside a parts array) makes the real converter throw
+// ("Cannot read properties of null"), which is the actual production
+// "bricked chat" mechanism this fix defends against. Asserting against the real
+// converter (rather than a mock-shaped error) is the whole point — a mock would
+// hide a version change in the converter's throw behaviour.
+import { convertToModelMessages, type UIMessage } from 'ai';
+import {
+  sanitizeUserParts,
+  convertHistoryResilient,
+  TOOL_CONTEXT_OMITTED_MARKER,
+} from './ai-chat.service';
+
+type Row = Omit<UIMessage, 'id'> & { id: string };
+
+describe('sanitizeUserParts (#489, branch: validation on receipt)', () => {
+  it('keeps whitelisted text parts unchanged', () => {
+    const drops: string[] = [];
+    const out = sanitizeUserParts(
+      [
+        { type: 'text', text: 'a' },
+        { type: 'text', text: 'b' },
+      ] as UIMessage['parts'],
+      (t) => drops.push(t),
+    );
+    expect(out).toEqual([
+      { type: 'text', text: 'a' },
+      { type: 'text', text: 'b' },
+    ]);
+    expect(drops).toEqual([]);
+  });
+
+  it('drops a non-text part (a tool-part in input-available) and reports its type', () => {
+    const drops: string[] = [];
+    const out = sanitizeUserParts(
+      [
+        { type: 'text', text: 'hi' },
+        {
+          type: 'tool-getPage',
+          toolCallId: 't1',
+          state: 'input-available',
+          input: { pageId: 'p' },
+        },
+      ] as unknown as UIMessage['parts'],
+      (t) => drops.push(t),
+    );
+    expect(out).toEqual([{ type: 'text', text: 'hi' }]);
+    expect(drops).toEqual(['tool-getPage']);
+  });
+
+  it('drops a null part (the shape that would poison convertToModelMessages)', () => {
+    const drops: string[] = [];
+    const out = sanitizeUserParts(
+      [{ type: 'text', text: 'hi' }, null] as unknown as UIMessage['parts'],
+      (t) => drops.push(t),
+    );
+    expect(out).toEqual([{ type: 'text', text: 'hi' }]);
+    expect(drops).toEqual(['(unknown)']);
+  });
+
+  it('returns undefined when nothing survives (so a null metadata is persisted)', () => {
+    const out = sanitizeUserParts(
+      [
+        { type: 'tool-x', toolCallId: 't', state: 'input-available' },
+      ] as unknown as UIMessage['parts'],
+      () => undefined,
+    );
+    expect(out).toBeUndefined();
+  });
+
+  it('returns undefined for a non-array input', () => {
+    expect(
+      sanitizeUserParts(undefined as unknown as UIMessage['parts'], () => undefined),
+    ).toBeUndefined();
+  });
+});
+
+describe('convertHistoryResilient (#489, branches: happy + per-row degradation)', () => {
+  it('happy path: healthy history converts identically to convertToModelMessages, no degrade', async () => {
+    const history: Row[] = [
+      { id: 'u1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
+      { id: 'a1', role: 'assistant', parts: [{ type: 'text', text: 'hello' }] },
+    ];
+    const degrades: number[] = [];
+    const out = await convertHistoryResilient(history, (i) => degrades.push(i));
+    const expected = await convertToModelMessages(history as UIMessage[]);
+    expect(out).toEqual(expected);
+    expect(degrades).toEqual([]);
+  });
+
+  it('REAL poison: a null part throws in the batch converter but is isolated and degraded to a marker', async () => {
+    // Sanity: the real converter genuinely throws on this shape.
+    const poisoned: Row = {
+      id: 'a1',
+      role: 'assistant',
+      parts: [
+        { type: 'text', text: 'earlier answer' },
+        null,
+      ] as unknown as UIMessage['parts'],
+    };
+    await expect(
+      convertToModelMessages([poisoned as UIMessage]),
+    ).rejects.toThrow();
+
+    const history: Row[] = [
+      { id: 'u1', role: 'user', parts: [{ type: 'text', text: 'first' }] },
+      poisoned,
+      { id: 'u2', role: 'user', parts: [{ type: 'text', text: 'second' }] },
+    ];
+    const degrades: number[] = [];
+    const out = await convertHistoryResilient(history, (i) => degrades.push(i));
+
+    // Only the poisoned row (index 1) is degraded.
+    expect(degrades).toEqual([1]);
+    // Healthy rows survive verbatim.
+    const flat = JSON.stringify(out);
+    expect(flat).toContain('first');
+    expect(flat).toContain('second');
+    // The degraded row carries its readable text AND the truncation marker so the
+    // model sees that tool context was omitted (never a silent loss).
+    expect(flat).toContain('earlier answer');
+    expect(flat).toContain(TOOL_CONTEXT_OMITTED_MARKER);
+    // The whole batch converted (3 model messages, none dropped).
+    expect(out).toHaveLength(3);
+  });
+
+  it('a fully-poisoned row (no readable text) still degrades to just the marker', async () => {
+    const history: Row[] = [
+      {
+        id: 'a1',
+        role: 'assistant',
+        parts: [null] as unknown as UIMessage['parts'],
+      },
+    ];
+    const out = await convertHistoryResilient(history, () => undefined);
+    expect(out).toHaveLength(1);
+    expect(JSON.stringify(out)).toContain(TOOL_CONTEXT_OMITTED_MARKER);
+  });
+});

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

@@ -97,8 +97,14 @@ describe('AiChatService.stream run-lifecycle safety net (#184)', () => {
     };
     const runService = new AiChatRunService(runRepo as never, { isCloud: () => false } as never);
 
-    // The user-message insert (the first bare await after beginRun) throws.
+    // The user-message insert throws. #489 runs the history load + convert BEFORE
+    // the insert (convert-before-insert, so a retry cannot duplicate the user row),
+    // so `findAllByChat` (a real repo method) is now called first — stub it to an
+    // empty history so the flow reaches the insert. Both awaits are AFTER beginRun,
+    // so the "exception after beginRun -> settled to error" invariant is unchanged;
+    // the throw point simply moved from insert to a later insert after a no-op load.
     const aiChatMessageRepo = {
+      findAllByChat: jest.fn().mockResolvedValue([]),
       insert: jest.fn().mockRejectedValue(new Error('insert boom')),
     };
     const aiChatRepo = {

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

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

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

@@ -13,6 +13,7 @@ import {
   compactToolOutput,
   assistantParts,
   serializeSteps,
+  type StepPartsCache,
   rowToUiMessage,
   prepareAgentStep,
   stepBudgetWarning,
@@ -28,10 +29,14 @@ import {
   FINAL_STEP_NUDGE,
   STEP_LIMIT_NO_ANSWER_MARKER,
   OUTPUT_DEGENERATION_ERROR,
+  lastAssistantContextTokens,
+  lastAssistantReplayOverflow,
+  seedActivatedTools,
 } from './ai-chat.service';
 import type { AiChatMessage, Workspace } from '@docmost/db/types/entity.types';
 import { buildSystemPrompt } from './ai-chat.prompt';
 import type { McpClientsService } from './external-mcp/mcp-clients.service';
+import { resolveEffectiveReplayThreshold } from './history-budget';
 
 /**
  * Unit tests for compactToolOutput: the pure helper that shrinks tool outputs
@@ -114,6 +119,54 @@ describe('compactToolOutput', () => {
 describe('assistantParts', () => {
   type AnyPart = Record<string, unknown>;
 
+  // #490 memoization: assistantParts builds each step's parts once and caches
+  // them by the step OBJECT's identity, so a mid-stream flush does not
+  // re-stringify every prior step's (large) output. Observable property: with a
+  // shared cache, the second call over the SAME step object returns the cached
+  // (identical) part array even if the step's underlying output was swapped —
+  // proving the work was memoized, not redone.
+  it('memoizes a step by identity (shared cache => one build per step)', () => {
+    const cache: StepPartsCache = new WeakMap();
+    const step = {
+      text: 'x',
+      toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+      toolResults: [{ toolCallId: 'c1', toolName: 'getPage', output: { v: 1 } }],
+    };
+    const first = assistantParts([step], '', cache) as AnyPart[];
+    expect((first.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      1,
+    );
+    // Swap the output for a NEW value; a re-build would pick it up, a cache hit
+    // keeps the first result.
+    step.toolResults[0] = {
+      toolCallId: 'c1',
+      toolName: 'getPage',
+      output: { v: 2 },
+    };
+    const second = assistantParts([step], '', cache) as AnyPart[];
+    expect((second.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      1,
+    );
+    // Same cached part objects are reused.
+    expect(second.find((p) => p.type === 'tool-getPage')).toBe(
+      first.find((p) => p.type === 'tool-getPage'),
+    );
+  });
+
+  it('without a cache, each call rebuilds (no stale memo)', () => {
+    const step = {
+      text: 'x',
+      toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+      toolResults: [{ toolCallId: 'c1', toolName: 'getPage', output: { v: 1 } }],
+    };
+    const first = assistantParts([step], '') as AnyPart[];
+    step.toolResults[0].output = { v: 2 };
+    const second = assistantParts([step], '') as AnyPart[];
+    expect((second.find((p) => p.type === 'tool-getPage')!.output as any).v).toBe(
+      2,
+    );
+  });
+
   it('emits output-available for a tool-call WITH a paired result', () => {
     const steps = [
       {
@@ -231,61 +284,320 @@ describe('assistantParts', () => {
   });
 });
 
-describe('serializeSteps', () => {
+// #490 trace format v2: per call the trace stores { input } for the call and an
+// OUTCOME element — { ok: true } on success, { error, kind: 'thrown' } on a
+// thrown tool-error, { error, kind: 'interrupted' } on a mid-step abort. The tool
+// OUTPUT is no longer duplicated here (it lives once in metadata.parts).
+describe('serializeSteps (trace v2)', () => {
   it('returns null when there are no calls or results', () => {
     expect(serializeSteps([])).toBeNull();
   });
 
-  it('flattens calls and results into a compact trace', () => {
+  it('pairs a successful call with an { ok: true } outcome and NO output', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'getPage', input: { id: 'p1' } }],
-        toolResults: [{ toolName: 'getPage', output: { title: 'T' } }],
+        toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: { id: 'p1' } }],
+        toolResults: [{ toolCallId: 'c1', toolName: 'getPage' }],
       },
     ]) as Array<Record<string, unknown>>;
     expect(trace).toHaveLength(2);
     expect(trace[0]).toEqual({ toolName: 'getPage', input: { id: 'p1' } });
-    expect(trace[1]).toEqual({ toolName: 'getPage', output: { title: 'T' } });
+    expect(trace[1]).toEqual({ toolName: 'getPage', ok: true });
+    // The output is NOT stored in the trace any more (dedup: it lives in parts).
+    expect(trace.some((e) => 'output' in e)).toBe(false);
   });
 
-  it('records a THROWN tool failure (tool-error part) with its error message', () => {
+  it('records a THROWN failure with { error, kind: "thrown" }', () => {
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'editPageText', input: { id: 'p1' } }],
+        toolCalls: [
+          { toolCallId: 'c1', toolName: 'editPageText', input: { id: 'p1' } },
+        ],
         toolResults: [],
         content: [
           {
             type: 'tool-error',
+            toolCallId: 'c1',
             toolName: 'editPageText',
             error: new Error('page is locked'),
           },
         ],
       },
     ]) as Array<Record<string, unknown>>;
-    // The call element is followed by a paired error element (mirroring how a
-    // successful result is appended), so the failure survives in the trace.
     expect(trace).toHaveLength(2);
     expect(trace[0]).toEqual({ toolName: 'editPageText', input: { id: 'p1' } });
     expect(trace[1]).toEqual({
       toolName: 'editPageText',
       error: 'page is locked',
+      kind: 'thrown',
     });
   });
 
-  it('truncates a very long tool-error message to the tool-output limit', () => {
+  it('marks an interrupted call (no result, no throw) with kind "interrupted"', () => {
+    const trace = serializeSteps([
+      {
+        toolCalls: [
+          { toolCallId: 'c1', toolName: 'createComment', input: { x: 1 } },
+        ],
+        toolResults: [],
+        content: [],
+      },
+    ]) as Array<Record<string, unknown>>;
+    expect(trace).toHaveLength(2);
+    expect(trace[1]).toEqual({
+      toolName: 'createComment',
+      error: 'Tool call did not complete.',
+      kind: 'interrupted',
+    });
+    // Structurally distinct from a thrown hard-fail so it never inflates an
+    // error-rate scan.
+    expect((trace[1] as { kind: string }).kind).not.toBe('thrown');
+  });
+
+  it('truncates a very long thrown-error message to the tool-output limit', () => {
     const long = 'x'.repeat(5000);
     const trace = serializeSteps([
       {
-        toolCalls: [{ toolName: 'editPageText', input: {} }],
+        toolCalls: [{ toolCallId: 'c1', toolName: 'editPageText', input: {} }],
         toolResults: [],
-        content: [{ type: 'tool-error', toolName: 'editPageText', error: long }],
+        content: [
+          {
+            type: 'tool-error',
+            toolCallId: 'c1',
+            toolName: 'editPageText',
+            error: long,
+          },
+        ],
       },
     ]) as Array<Record<string, unknown>>;
     const errorText = trace[1].error as string;
-    // Truncated (not the full 5000 chars) and carries the omission marker.
     expect(errorText.length).toBeLessThan(long.length);
     expect(errorText).toContain('chars omitted');
   });
+
+  it('pairs parallel calls in one step with their outcomes by id', () => {
+    const trace = serializeSteps([
+      {
+        toolCalls: [
+          { toolCallId: 'a', toolName: 'getPage', input: {} },
+          { toolCallId: 'b', toolName: 'searchPages', input: {} },
+        ],
+        toolResults: [{ toolCallId: 'b', toolName: 'searchPages' }],
+        content: [
+          { type: 'tool-error', toolCallId: 'a', toolName: 'getPage', error: 'nope' },
+        ],
+      },
+    ]) as Array<Record<string, unknown>>;
+    // call a, outcome a (thrown), call b, outcome b (ok)
+    expect(trace).toHaveLength(4);
+    expect(trace[1]).toEqual({ toolName: 'getPage', error: 'nope', kind: 'thrown' });
+    expect(trace[3]).toEqual({ toolName: 'searchPages', ok: true });
+  });
+});
+
+// #490: every assistant row flushAssistant writes carries the v2 era marker so a
+// dual-shape diagnostic query can branch on the trace shape without inspecting it.
+describe('toolTraceVersion era marker (#490)', () => {
+  it('stamps metadata.toolTraceVersion = 2 on every flushed row', () => {
+    const seed = flushAssistant([], '', 'streaming');
+    expect(seed.metadata.toolTraceVersion).toBe(2);
+    const done = flushAssistant(
+      [
+        {
+          text: 'ok',
+          toolCalls: [{ toolCallId: 'c1', toolName: 'getPage', input: {} }],
+          toolResults: [{ toolCallId: 'c1', toolName: 'getPage' }],
+        },
+      ],
+      '',
+      'completed',
+      { finishReason: 'stop' },
+    );
+    expect(done.metadata.toolTraceVersion).toBe(2);
+  });
+});
+
+// #490 replay-budget signal helpers over persisted history.
+describe('lastAssistantContextTokens', () => {
+  const row = (
+    role: string,
+    metadata: Record<string, unknown> | null,
+  ): AiChatMessage => ({ role, metadata }) as unknown as AiChatMessage;
+
+  it('reads the most recent assistant turn contextTokens (provider fact)', () => {
+    const hist = [
+      row('user', null),
+      row('assistant', { contextTokens: 12000 }),
+      row('user', null),
+      row('assistant', { contextTokens: 41000 }),
+    ];
+    expect(lastAssistantContextTokens(hist)).toBe(41000);
+  });
+
+  it('returns undefined when the last assistant turn recorded no usage', () => {
+    const hist = [row('assistant', { error: 'boom' }), row('user', null)];
+    expect(lastAssistantContextTokens(hist)).toBeUndefined();
+    expect(lastAssistantContextTokens([])).toBeUndefined();
+  });
+});
+
+// #490 snapshotOpenPage fast-path: skip the full Markdown export + upsert when a
+// snapshot already exists at the page's CURRENT version (same updated_at instant).
+describe('snapshotOpenPage fast-path (#490)', () => {
+  function makeSvc(existingSnapshot: unknown, pageUpdatedAt: Date) {
+    const exportPageMarkdown = jest.fn(async () => '# md');
+    const upsert = jest.fn(async () => undefined);
+    const findByChatPage = jest.fn(async () => existingSnapshot);
+    const pageRepo = {
+      findById: jest.fn(async () => ({
+        id: 'p1',
+        workspaceId: 'ws1',
+        updatedAt: pageUpdatedAt,
+      })),
+    };
+    const svc = new AiChatService(
+      {} as never, // ai
+      {} as never, // aiChatRepo
+      {} as never, // aiChatMessageRepo
+      { findByChatPage, upsert } as never, // aiChatPageSnapshotRepo
+      {} as never, // aiSettings
+      { exportPageMarkdown } as never, // tools
+      {} as never, // mcpClients
+      {} as never, // aiAgentRoleRepo
+      pageRepo as never, // pageRepo
+      {} as never, // pageAccess
+      {} as never, // environment
+    );
+    return { svc, exportPageMarkdown, upsert, findByChatPage };
+  }
+
+  const args = () =>
+    [
+      'chat1',
+      'p1',
+      { id: 'ws1' } as never,
+      { id: 'u1' } as never,
+      'sess',
+    ] as const;
+
+  it('skips export + upsert when the snapshot is already at this page version', async () => {
+    const t = new Date('2026-07-07T10:00:00Z');
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      { pageUpdatedAt: t, contentMd: '# md' },
+      t,
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).not.toHaveBeenCalled();
+    expect(upsert).not.toHaveBeenCalled();
+  });
+
+  it('exports + upserts when the page advanced since the snapshot', async () => {
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      { pageUpdatedAt: new Date('2026-07-07T10:00:00Z'), contentMd: 'old' },
+      new Date('2026-07-07T11:00:00Z'),
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).toHaveBeenCalledTimes(1);
+    expect(upsert).toHaveBeenCalledTimes(1);
+  });
+
+  it('seeds (exports + upserts) on the first turn (no snapshot yet)', async () => {
+    const { svc, exportPageMarkdown, upsert } = makeSvc(
+      undefined,
+      new Date('2026-07-07T10:00:00Z'),
+    );
+    await (svc as unknown as { snapshotOpenPage: (...a: unknown[]) => Promise<void> })
+      .snapshotOpenPage(...args());
+    expect(exportPageMarkdown).toHaveBeenCalledTimes(1);
+    expect(upsert).toHaveBeenCalledTimes(1);
+  });
+});
+
+// #490 deferred-tool activation persisted across turns.
+describe('seedActivatedTools', () => {
+  const valid = new Set(['Search_web', 'getPageJson', 'diffPageVersions']);
+
+  it('seeds from persisted metadata, intersected with current valid names', () => {
+    expect(
+      seedActivatedTools(
+        { activatedTools: ['Search_web', 'getPageJson'] },
+        valid,
+      ),
+    ).toEqual(['Search_web', 'getPageJson']);
+  });
+
+  it('drops a stored tool that is no longer valid (allowlist/role changed)', () => {
+    // 'Habr_publish' was activated before but is not in the current allowlist.
+    expect(
+      seedActivatedTools({ activatedTools: ['Search_web', 'Habr_publish'] }, valid),
+    ).toEqual(['Search_web']);
+  });
+
+  it('is empty/robust for missing, non-array, or unknown-shaped metadata', () => {
+    expect(seedActivatedTools(undefined, valid)).toEqual([]);
+    expect(seedActivatedTools({}, valid)).toEqual([]);
+    expect(seedActivatedTools({ activatedTools: 'nope' }, valid)).toEqual([]);
+    expect(
+      seedActivatedTools({ activatedTools: [1, 'getPageJson', null] }, valid),
+    ).toEqual(['getPageJson']);
+  });
+
+  it('de-duplicates stored names', () => {
+    expect(
+      seedActivatedTools(
+        { activatedTools: ['getPageJson', 'getPageJson'] },
+        valid,
+      ),
+    ).toEqual(['getPageJson']);
+  });
+});
+
+describe('lastAssistantReplayOverflow', () => {
+  const row = (
+    role: string,
+    metadata: Record<string, unknown> | null,
+  ): AiChatMessage => ({ role, metadata }) as unknown as AiChatMessage;
+
+  it('is true only when the LAST assistant turn overflowed', () => {
+    expect(
+      lastAssistantReplayOverflow([
+        row('assistant', { replayOverflow: true }),
+        row('user', null),
+      ]),
+    ).toBe(true);
+    // A recovered (later, non-overflow) assistant turn clears it.
+    expect(
+      lastAssistantReplayOverflow([
+        row('assistant', { replayOverflow: true }),
+        row('user', null),
+        row('assistant', { contextTokens: 5 }),
+      ]),
+    ).toBe(false);
+    expect(lastAssistantReplayOverflow([])).toBe(false);
+  });
+
+  // #490 reactive recovery: a prior turn stamped `replayOverflow` must make the
+  // NEXT turn's effective budget the AGGRESSIVE 0.5x cut — that harder trim is
+  // what un-bricks a chat that just 400'd on the context window. This exercises
+  // the exact wiring the service uses: read the stamp, then scale the threshold.
+  it('#490: a prior replayOverflow drives the next turn to the 0.5x aggressive budget', () => {
+    const history = [
+      row('assistant', { replayOverflow: true }),
+      row('user', null),
+    ];
+    const priorOverflowed = lastAssistantReplayOverflow(history);
+    expect(priorOverflowed).toBe(true);
+    // Base budget 100k -> aggressive recovery halves it to 50k this turn.
+    expect(resolveEffectiveReplayThreshold(100_000, priorOverflowed)).toBe(50_000);
+    // Odd base floors, not rounds.
+    expect(resolveEffectiveReplayThreshold(99_999, true)).toBe(49_999);
+    // No prior overflow -> the base budget is used verbatim (no aggressive cut).
+    expect(resolveEffectiveReplayThreshold(100_000, false)).toBe(100_000);
+    // An explicit off-switch (null) is never overridden, even on recovery.
+    expect(resolveEffectiveReplayThreshold(null, true)).toBeNull();
+  });
 });
 
 describe('rowToUiMessage', () => {
@@ -618,6 +930,23 @@ describe('flushAssistant', () => {
     expect(flushed.metadata.error).toBe('boom');
   });
 
+  // #490 observability: the replay budgeter's decision is stamped on the turn.
+  it('records replayTrimmedToTokens + replayOverflow when provided', () => {
+    const f = flushAssistant([], '', 'error', {
+      error: 'ctx',
+      replayTrimmedToTokens: 42_000,
+      replayOverflow: true,
+    });
+    expect(f.metadata.replayTrimmedToTokens).toBe(42_000);
+    expect(f.metadata.replayOverflow).toBe(true);
+  });
+
+  it('omits the replay metadata when not provided', () => {
+    const f = flushAssistant([], '', 'completed', { finishReason: 'stop' });
+    expect('replayTrimmedToTokens' in f.metadata).toBe(false);
+    expect('replayOverflow' in f.metadata).toBe(false);
+  });
+
   // #274 observability: the page-change diff the agent saw this turn is persisted
   // to metadata.pageChanged when a non-empty diff was injected, and omitted when
   // the diff is empty/whitespace or the arg is not supplied.
@@ -1440,7 +1769,7 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
   }
 
   // Wire only the deps reached on the way to the pipe call, plus a spy registry.
-  function makeService(opts: { resumable: boolean }) {
+  function makeService(opts: { resumable: boolean; history?: unknown[] }) {
     const aiChatRepo = {
       findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
       insert: jest.fn(),
@@ -1448,7 +1777,7 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
     const aiChatMessageRepo = {
       // Both the user insert and the assistant seed return the same row id.
       insert: jest.fn(async () => ({ id: 'msg-1' })),
-      findAllByChat: jest.fn(async () => []),
+      findAllByChat: jest.fn(async () => opts.history ?? []),
       update: jest.fn(async () => ({ id: 'msg-1' })),
       // #487: the terminal owner-write + the opportunistic reconcile query.
       finalizeOwner: jest.fn(async () => ({ id: 'msg-1' })),
@@ -1487,7 +1816,7 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
       } as never,
       streamRegistry as never,
     );
-    return { svc, streamRegistry };
+    return { svc, streamRegistry, aiChatMessageRepo };
   }
 
   const body = {
@@ -1570,6 +1899,86 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
     await expect(drive(svc, makeRunHooks())).rejects.toThrow('boom');
     expect(streamRegistry.abortEntry).toHaveBeenCalledWith('chat-1', 'run-1');
   });
+
+  // #489 REGRESSION (against the REAL convertToModelMessages — not mocked here):
+  // a persisted history row whose parts contain a `null` element makes the real
+  // convertToModelMessages THROW ("Cannot read properties of null"). Pre-fix that
+  // 500-ed every turn forever and each retry appended a duplicate user row. The
+  // fix converts BEFORE the insert and isolates the poisoned row per-row, degrading
+  // it to text with a "[tool context omitted]" marker. Assert the turn still runs,
+  // the marker reaches the model, and exactly ONE user row is inserted.
+  it('#489: a poisoned OLD-history row keeps the chat working; the marker reaches the model; one user insert', async () => {
+    const { svc, aiChatMessageRepo } = makeService({
+      resumable: false,
+      history: [
+        {
+          id: 'old-1',
+          role: 'assistant',
+          content: 'earlier answer',
+          // A null part is the poison: rowToUiMessage keeps it (the array is
+          // non-empty) and the real convertToModelMessages throws on it.
+          metadata: { parts: [{ type: 'text', text: 'earlier answer' }, null] },
+          status: 'completed',
+        },
+      ],
+    });
+    // Must NOT throw — the poisoned row is degraded, not fatal.
+    await drive(svc, makeRunHooks());
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+    const passedMessages = streamTextMock.mock.calls[0][0].messages;
+    const serialized = JSON.stringify(passedMessages);
+    // The model sees the truncation marker (silent tool-context loss is not ok)
+    // AND the row's readable text is preserved alongside it.
+    expect(serialized).toContain('[tool context omitted]');
+    expect(serialized).toContain('earlier answer');
+    // Exactly ONE user row inserted (no duplicate), inserted AFTER conversion.
+    const userInserts = aiChatMessageRepo.insert.mock.calls
+      .map((c: unknown[]) => c[0] as { role?: string })
+      .filter((r) => r.role === 'user');
+    expect(userInserts).toHaveLength(1);
+  });
+
+  // #489: client-supplied non-text parts (a tool-part in `input-available`, the
+  // exact "bricking" payload) are dropped ON RECEIPT — never persisted — so they
+  // can never poison future turns. Only the text survives into metadata.parts.
+  it('#489: a non-text client part is stripped before persist (only text survives)', async () => {
+    const { svc, aiChatMessageRepo } = makeService({ resumable: false });
+    await svc.stream({
+      user: { id: 'u1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 's1',
+      body: {
+        chatId: 'chat-1',
+        messages: [
+          {
+            id: 'm1',
+            role: 'user',
+            parts: [
+              { type: 'text', text: 'hello' },
+              // untrusted tool-part — must be dropped, never persisted
+              {
+                type: 'tool-getPage',
+                toolCallId: 't1',
+                state: 'input-available',
+                input: { pageId: 'p' },
+              },
+            ],
+          },
+        ],
+      } as never,
+      res: makeRes() as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      runHooks: makeRunHooks() as never,
+    });
+    const userInsert = aiChatMessageRepo.insert.mock.calls
+      .map((c: unknown[]) => c[0] as { role?: string; metadata?: unknown })
+      .find((r) => r.role === 'user');
+    const parts = (userInsert?.metadata as { parts?: Array<{ type: string }> })
+      ?.parts;
+    expect(parts).toEqual([{ type: 'text', text: 'hello' }]);
+  });
 });
 
 /**

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

@@ -14,6 +14,7 @@ import {
   convertToModelMessages,
   stepCountIs,
   type UIMessage,
+  type ModelMessage,
   type LanguageModel,
 } from 'ai';
 import { AiService } from '../../integrations/ai/ai.service';
@@ -54,6 +55,12 @@ import {
   type SelectionContext,
 } from './tools/current-page.util';
 import { roleModelOverride } from './roles/role-model-config';
+import {
+  resolveReplayBudget,
+  resolveEffectiveReplayThreshold,
+  isContextOverflowError,
+  trimHistoryForReplay,
+} from './history-budget';
 import {
   startSseHeartbeat,
   stripStreamingHopByHopHeaders,
@@ -116,9 +123,14 @@ const FINAL_STEP_NUDGE =
 // NO text at all (#444, mitigates the "empty turn" the lockdown used to prevent
 // when the toggle is OFF). Makes the exhausted-without-answer state explicit to
 // the user and, on replay, to the model on the next turn.
+// The persisted content is the app's base locale (en-US) — which is ALSO the
+// i18n key the client localizes through `t()` — instead of a hardcoded Russian
+// string (it used to render Russian for every locale, and fed Russian back to
+// the model on replay). Keep it a plain, model-readable English sentence so the
+// next turn's replay reads cleanly; the client resolves the locale.
 const STEP_LIMIT_NO_ANSWER_MARKER =
-  '(Достигнут лимит шагов — итоговый ответ не сформулирован; работа могла ' +
-  'остаться незавершённой. Напишите «продолжай», чтобы агент продолжил.)';
+  '(Step limit reached — no final answer was produced; the work may be ' +
+  'unfinished. Reply "continue" to let the agent carry on.)';
 
 // Reason recorded in ai_chat_runs.error / the assistant row when the token-
 // degeneration detector (#444) aborts a run. Distinct from a user Stop (no error)
@@ -126,6 +138,15 @@ const STEP_LIMIT_NO_ANSWER_MARKER =
 const OUTPUT_DEGENERATION_ERROR =
   'Output degeneration detected (repeated token loop)';
 
+// Prefix recorded on the assistant row when the provider rejected the turn for
+// CONTEXT OVERFLOW (#490): the replayed history exceeded the model's window. The
+// row is ALSO stamped `metadata.replayOverflow` so the NEXT turn's budgeter trims
+// aggressively (the reactive recovery — the overflowing turn had no usage signal
+// to trigger preventive trimming, so the classified 400 is what un-bricks it).
+export const CONTEXT_OVERFLOW_ERROR_PREFIX =
+  'Диалог превысил контекстное окно модели; история будет агрессивно ' +
+  'сокращена на следующем ходу.';
+
 /**
  * Compute the step-budget warning text (#444), or '' when this step is outside
  * the warning band. The warning fires on steps
@@ -881,6 +902,21 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const freshPage = await this.pageRepo.findById(pageId);
       // Page deleted during the turn (or somehow foreign) => don't write.
       if (!freshPage || freshPage.workspaceId !== workspace.id) return;
+      // Fast-path (#490): if a snapshot already exists at THIS page version
+      // (same updated_at instant), its content is already current — skip the full
+      // Markdown export + upsert entirely. A turn that did NOT touch the open page
+      // (the common case) thus does no snapshot work. This mirrors the read-side
+      // fast path in detectPageChange (sameInstant): both trust that a page edit
+      // bumps updated_at. When the agent (or a human) DID edit the page this turn,
+      // updated_at advanced, so this does not match and we re-export as before.
+      const existing = await this.aiChatPageSnapshotRepo.findByChatPage(
+        chatId,
+        pageId,
+        workspace.id,
+      );
+      if (existing && sameInstant(existing.pageUpdatedAt, freshPage.updatedAt)) {
+        return;
+      }
       const currentMd = await this.tools.exportPageMarkdown(
         user,
         sessionId,
@@ -920,10 +956,17 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
     // supplied or the supplied one does not belong to this workspace.
     let isNewChat = false;
     let chatId = body.chatId;
+    // Persisted chat-level metadata bag (#490): read once here so the deferred-tool
+    // activation set can be seeded from the previous turn. Undefined for a new chat.
+    let chatMetadata: Record<string, unknown> | undefined;
     if (chatId) {
       const existing = await this.aiChatRepo.findById(chatId, workspace.id);
       if (!existing) {
         chatId = undefined;
+      } else {
+        chatMetadata = (existing.metadata ?? undefined) as
+          | Record<string, unknown>
+          | undefined;
       }
     }
     // The open page the client sent is attacker-controllable — BOTH its id and
@@ -1042,7 +1085,58 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const incoming = lastUserMessage(body.messages);
       const incomingText = uiMessageText(incoming);
 
-      // Persist the user message before contacting the model.
+      // #489: sanitize client-supplied parts ON RECEIPT. The client only ever
+      // sends `sendMessage({ text })` (a single text part); there is no
+      // file/attachment path. Any other part — most dangerously a tool-part in
+      // `input-available` state — is untrusted data that, once persisted to
+      // `metadata.parts` verbatim, is REPLAYED through convertToModelMessages on
+      // every later turn. A malformed tool-part makes that conversion throw,
+      // 500-ing every future turn of the chat forever ("bricked"). Drop any
+      // non-whitelisted part with a warn.
+      const sanitizedParts = sanitizeUserParts(incoming?.parts, (type) =>
+        this.logger.warn(
+          `Dropping unsupported user message part '${type}' on chat ${chatId}`,
+        ),
+      );
+
+      // #489: rebuild the conversation from persisted history (not the client
+      // payload) and CONVERT it to model messages BEFORE persisting the user row.
+      // Load the OLD history (WITHOUT the new row) and append the incoming turn in
+      // memory for the conversion. This makes the insert happen only after a
+      // successful conversion, so a conversion failure cannot leave a DUPLICATE
+      // user row behind on the client's retry (the "bricked chat" that accreted a
+      // dup on every 500). `findAllByChat` returns chronological order (oldest ->
+      // newest) and keeps a 5000-row memory-safety backstop (on overflow it keeps
+      // the NEWEST rows and logs a warning); that is a safety net far above any
+      // realistic chat, not a conversational limit.
+      const oldHistory = await this.aiChatMessageRepo.findAllByChat(
+        chatId,
+        workspace.id,
+      );
+      const uiMessages: Array<Omit<UIMessage, 'id'> & { id: string }> = [
+        ...oldHistory.map(rowToUiMessage),
+        {
+          id: 'pending-user',
+          role: 'user',
+          parts: (sanitizedParts && sanitizedParts.length > 0
+            ? sanitizedParts
+            : textPart(incomingText)) as UIMessage['parts'],
+        },
+      ];
+      // convertToModelMessages is async in ai@6.0.134 (returns Promise<ModelMessage[]>).
+      // Resilient (#489): a single poisoned row in the OLD history is isolated via
+      // 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) =>
+        this.logger.warn(
+          `Degraded unconvertible history row ${index} on chat ${chatId} to text: ${
+            err instanceof Error ? err.message : 'unknown error'
+          }`,
+        ),
+      );
+
+      // Persist the user message only AFTER a successful conversion (#489).
       await this.aiChatMessageRepo.insert({
         chatId,
         workspaceId: workspace.id,
@@ -1050,31 +1144,21 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
         role: 'user',
         content: incomingText,
         // jsonb column: UIMessage parts are JSON-serializable at runtime but not
-        // structurally `JsonValue`, so cast through unknown.
-        metadata: (incoming?.parts ? { parts: incoming.parts } : null) as never,
+        // structurally `JsonValue`, so cast through unknown. Persist the SANITIZED
+        // parts (never the raw client parts) so the row is always convertible.
+        metadata: (sanitizedParts ? { parts: sanitizedParts } : null) as never,
       });
 
-      // Rebuild the conversation from persisted history (not the client payload),
-      // so the model always sees the authoritative server-side transcript. Load
-      // the FULL history in chronological order (oldest -> newest, incl. the user
-      // message just inserted above) so NO turns are dropped — there is no
-      // recent-tail window anymore. `findAllByChat` keeps a 5000-row memory-safety
-      // backstop (on overflow it keeps the NEWEST rows and logs a warning); that
-      // is a safety net far above any realistic chat, not a conversational limit.
-      const history = await this.aiChatMessageRepo.findAllByChat(
-        chatId,
-        workspace.id,
-      );
-      const uiMessages = history.map(rowToUiMessage);
-      // convertToModelMessages is async in ai@6.0.134 (returns Promise<ModelMessage[]>).
-      const messages = await convertToModelMessages(uiMessages);
-
       // Interrupt-resume detection (#198): the client "send now" flag is only a
       // hint — confirm it against the persisted history (the preceding assistant
       // turn must really be aborted/streaming) so a spoofed flag cannot inject the
       // interrupt note onto an ordinary turn. The partial output the model needs is
       // already in `messages` (the aborted assistant row replays via findRecent).
-      const interrupted = isInterruptResume(history, body.interrupted);
+      // Append the new user turn (shape-only) so index -2 is the prior assistant.
+      const interrupted = isInterruptResume(
+        [...oldHistory, { role: 'user', status: null, metadata: null }],
+        body.interrupted,
+      );
 
       // Per-turn page-change detection (#274): if the open page was hand-edited by
       // the user since the agent's last turn ended, compute the unified diff so the
@@ -1093,6 +1177,56 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // Here we only need the admin-configured system prompt.
       const resolved = await this.aiSettings.resolve(workspace.id);
 
+      // History-replay token budget (#490). The full conversation is replayed to
+      // the provider every turn, so a long chat eventually 400s on the context
+      // window — forever. Bound the REPLAYED history (never the persisted rows).
+      // PRIMARY signal is the provider's own fact: the last turn's contextTokens.
+      const replayBudget = resolveReplayBudget(resolved?.chatContextWindowRaw);
+      if (replayBudget.usedDefault) {
+        // The default fires precisely for installs with NO configured window —
+        // the ones that hit terminal overflow. Warn so it is observable.
+        this.logger.warn(
+          `AI chat (chat ${chatId}): no chatContextWindow configured; ` +
+            `applying the default replay budget (${replayBudget.thresholdTokens} tokens).`,
+        );
+      }
+      // Last turn's provider-reported context size (authoritative when present).
+      const priorContextTokens = lastAssistantContextTokens(oldHistory);
+      // Reactive recovery (#490): if the LAST turn was rejected for context
+      // overflow (stamped by onError), trim AGGRESSIVELY this turn — the
+      // overflowing turn produced no usage signal, so a normal-threshold trim may
+      // not shrink enough to fit. This is what un-bricks a chat that just 400'd.
+      const priorOverflowed = lastAssistantReplayOverflow(oldHistory);
+      const effectiveThreshold = resolveEffectiveReplayThreshold(
+        replayBudget.thresholdTokens,
+        priorOverflowed,
+      );
+      if (priorOverflowed) {
+        this.logger.warn(
+          `AI chat (chat ${chatId}): previous turn hit context overflow; ` +
+            `applying aggressive replay budget (${effectiveThreshold} tokens).`,
+        );
+      }
+      const preTrim = trimHistoryForReplay(
+        messages,
+        effectiveThreshold,
+        // A prior OVERFLOW means the provider count is stale/absent — force the
+        // char-estimate path by ignoring priorContextTokens on recovery.
+        priorOverflowed ? undefined : priorContextTokens,
+      );
+      messages = preTrim.messages;
+      // Observability (#490): record the budgeter's decision on the turn so the UI
+      // can surface "replay truncated at N tokens". Threaded into flushAssistant.
+      let replayTrimmedToTokens: number | undefined = preTrim.trimmed
+        ? preTrim.estimatedTokens
+        : undefined;
+      if (preTrim.trimmed) {
+        this.logger.log(
+          `AI chat (chat ${chatId}): replay history trimmed to ~${preTrim.estimatedTokens} ` +
+            `tokens (budget ${replayBudget.thresholdTokens}).`,
+        );
+      }
+
       // Build the external MCP toolset FIRST so the system prompt can carry each
       // connected server's admin-authored guidance (#180). Merge in admin-
       // configured external MCP tools (web search, etc.; §6.8). A down/slow
@@ -1284,10 +1418,19 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       //    tools + ALL external MCP tools), computed from the ACTUAL toolset so an
       //    external tool is loadable by its namespaced name. loadTools rejects any
       //    name outside this set.
-      const activatedTools = new Set<string>();
       const validDeferredNames = new Set<string>(
         Object.keys(baseTools).filter((k) => !CORE_TOOL_SET.has(k)),
       );
+      // #490: seed the activation set from the chat's PERSISTED set so the model
+      // does not re-run loadTools every turn to re-activate the same tools. Only
+      // when deferred loading is enabled, and ALWAYS intersected with the CURRENT
+      // valid deferred names — an allowlist/role change must never resurrect a tool
+      // that no longer exists (prepareAgentStep would get a phantom active name).
+      const activatedTools = new Set<string>(
+        deferredEnabled
+          ? seedActivatedTools(chatMetadata, validDeferredNames)
+          : [],
+      );
       // Add the loadTools meta-tool ONLY when the feature is enabled; when off the
       // toolset and behavior are exactly as before.
       const tools = deferredEnabled
@@ -1297,6 +1440,39 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
           }
         : baseTools;
 
+      // #490: persist the (deterministically ordered) activation set back onto the
+      // chat metadata at turn end, so the NEXT turn seeds from it. Once-guarded and
+      // skipped when nothing new was activated (the set equals its seed) so an
+      // ordinary turn adds no extra write. Preserves other metadata keys.
+      let activatedToolsPersisted = false;
+      const persistActivatedTools = async (): Promise<void> => {
+        if (!deferredEnabled || activatedToolsPersisted || !chatId) return;
+        activatedToolsPersisted = true;
+        const current = [...activatedTools].sort();
+        const seeded = seedActivatedTools(chatMetadata, validDeferredNames).sort();
+        if (current.length === 0 || current.join('') === seeded.join('')) {
+          return; // nothing new activated -> no write
+        }
+        try {
+          await this.aiChatRepo.update(
+            chatId,
+            {
+              metadata: {
+                ...(chatMetadata ?? {}),
+                activatedTools: current,
+              },
+            } as never,
+            workspace.id,
+          );
+        } catch (err) {
+          this.logger.warn(
+            `Failed to persist activated tools (chat ${chatId}): ${
+              err instanceof Error ? err.message : 'unknown error'
+            }`,
+          );
+        }
+      };
+
       // Accumulate the turn's streamed output so a provider error / disconnect can
       // persist the PARTIAL answer the user already saw — the SDK's onError/onAbort
       // callbacks don't hand us the in-progress text. `capturedSteps` holds finished
@@ -1305,6 +1481,11 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const capturedSteps: StepLike[] = [];
       let inProgressText = '';
 
+      // Per-turn step->parts memo (#490): shared across every flushAssistant call
+      // this turn so each finished step's (large) output is JSON-stringified ONCE,
+      // not re-stringified on every subsequent onStepFinish flush (was O(N²)).
+      const partsCache: StepPartsCache = new WeakMap();
+
       // Token-degeneration guard (#444). When the final-step lockdown is OFF, a
       // runaway repetition loop (the 255KB "loadTools." incident) is aborted via
       // this internal controller, unioned with the run/socket signal below. The
@@ -1362,27 +1543,39 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // Per-step (non-terminal) update: persist the finished steps the moment a
       // step ends. Tolerant — a failed update is logged and swallowed so it never
       // throws into the stream. Keeps status 'streaming'.
-      const updateStreaming = async (): Promise<void> => {
-        if (!assistantId) return;
+      //
+      // #491: it now SIGNALS its outcome — the persisted `stepsPersisted` count on
+      // a CONFIRMED write, or null when it was skipped/failed. The caller rotates
+      // the run-stream registry ring ONLY on a non-null return (a confirmed
+      // persist), so a failed persist never rotates away a step nobody has (the
+      // classic inversion bug); a failure just makes the ring cover more.
+      const updateStreaming = async (): Promise<number | null> => {
+        if (!assistantId) return null;
         // Cheap short-circuit once the turn is finalized (see `finalized` below).
         // The AUTHORITATIVE guard is `onlyIfStreaming` on the UPDATE: a late
         // fire-and-forget step update could still be in flight on another pool
         // connection when finalize runs, so the SQL `WHERE status='streaming'`
         // (not this flag) is what prevents it clobbering the terminal row.
-        if (finalized) return;
+        if (finalized) return null;
+        // Build the flush ONCE so the returned count is EXACTLY the persisted
+        // `stepsPersisted` (both derive from capturedSteps.length at this instant).
+        const flushed = flushAssistant(capturedSteps, '', 'streaming', {
+          pageChanged,
+          partsCache,
+        });
+        const stepsPersisted = flushed.metadata.stepsPersisted as number;
         try {
-          await this.aiChatMessageRepo.update(
-            assistantId,
-            workspace.id,
-            flushAssistant(capturedSteps, '', 'streaming', { pageChanged }),
-            { onlyIfStreaming: true },
-          );
+          await this.aiChatMessageRepo.update(assistantId, workspace.id, flushed, {
+            onlyIfStreaming: true,
+          });
+          return stepsPersisted;
         } catch (err) {
           this.logger.warn(
             `Failed to update streaming assistant row: ${
               err instanceof Error ? err.message : 'unknown error'
             }`,
           );
+          return null;
         }
       };
 
@@ -1472,6 +1665,13 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
           system,
           messages,
           tools,
+          // Pin the AI SDK per-request retry budget explicitly instead of relying
+          // on its default (which is also 2). Connection arithmetic per turn:
+          // (1 + maxRetries=2) × (1 + AI_STREAM_PRE_RESPONSE_RETRIES) network
+          // connects worst-case — the two retry layers compose, so making the SDK
+          // side explicit keeps that ceiling visible and pinned against SDK-default
+          // drift.
+          maxRetries: 2,
           // No maxOutputTokens cap on the agent: tool-call arguments (e.g. a full
           // page body for the write tools) are emitted as OUTPUT tokens, so a fixed
           // cap would truncate complex tool calls mid-argument. Let the model use its
@@ -1551,7 +1751,24 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // this point still recovers the step. Not awaited here (never block the
             // stream), but SERIALIZED via stepUpdateChain so the writes commit in
             // step order; updateStreaming is error-tolerant (logs + swallows).
-            stepUpdateChain = stepUpdateChain.then(() => updateStreaming());
+            // #491: on a CONFIRMED persist, rotate the run-stream registry ring to
+            // drop the now-on-disk steps (stamp < stepsPersisted). Gated on the
+            // resumable flag (same as open/bind) and identity-checked in the
+            // registry; a null return (skipped/failed) rotates NOTHING (auto-safe).
+            stepUpdateChain = stepUpdateChain.then(async () => {
+              const persisted = await updateStreaming();
+              if (
+                persisted != null &&
+                runId &&
+                this.environment?.isAiChatResumableStreamEnabled?.()
+              ) {
+                this.streamRegistry?.confirmPersistedStep(
+                  chatId,
+                  runId,
+                  persisted,
+                );
+              }
+            });
             // #184: persist the run's progress (finished-step count). Fire-and-
             // forget; the hook swallows its own errors.
             if (runId) runHooks?.onStep?.(runId, capturedSteps.length);
@@ -1607,6 +1824,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 // closure scope here). Omitted/0 = no limit.
                 maxContextTokens: resolved?.chatContextWindow,
                 pageChanged,
+                partsCache,
+                replayTrimmedToTokens,
               }),
             );
             // #184/#487: the RUN is finalized ALWAYS (never gated on the message).
@@ -1631,6 +1850,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // own edits are baked in — and this also SEEDS the snapshot on the first
             // turn. Runs once across every terminal path (see snapshotTurnEnd).
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
 
             // Generate the chat title for a freshly created chat AFTER the stream's
             // provider call has completed — NOT concurrently with it. The z.ai coding
@@ -1654,7 +1875,16 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // object, so the actual provider cause is clearly logged. Reuse the
             // shared formatter so provider error formatting stays unified.
             const e = error as { stack?: string };
-            const errorText = describeProviderError(error, String(error));
+            // #490 reactive branch: classify a CONTEXT-OVERFLOW rejection (the
+            // replayed history exceeded the model window). The overflowing turn had
+            // no prior usage to trigger preventive trimming, so we record a clear,
+            // distinguishable cause AND stamp the row so the NEXT turn's budgeter
+            // trims aggressively — the reactive recovery that un-bricks the chat.
+            const overflow = isContextOverflowError(error);
+            const providerError = describeProviderError(error, String(error));
+            const errorText = overflow
+              ? `${CONTEXT_OVERFLOW_ERROR_PREFIX} (${providerError})`
+              : providerError;
             this.logger.error(`AI chat stream error: ${errorText}`, e?.stack);
             // DIAGNOSTIC (Safari stream-drop investigation) — temporary: timing of
             // an error-terminated stream.
@@ -1672,6 +1902,9 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
               flushAssistant(capturedSteps, inProgressText, 'error', {
                 error: errorText,
                 pageChanged,
+                partsCache,
+                replayTrimmedToTokens,
+                replayOverflow: overflow || undefined,
               }),
             );
             // #184: settle the RUN as failed, carrying the provider/transport cause.
@@ -1681,6 +1914,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // committed before the error must be baked into the snapshot, or the
             // next turn would mis-report it as a user edit.
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
           },
           onAbort: async ({ steps }) => {
             // #444: distinguish a degeneration abort (our internal controller) from
@@ -1695,6 +1930,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 flushAssistant(capturedSteps, truncated, 'error', {
                   error: OUTPUT_DEGENERATION_ERROR,
                   pageChanged,
+                  partsCache,
                 }),
               );
               if (runId)
@@ -1705,6 +1941,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 );
               await closeExternalClients();
               await snapshotTurnEnd();
+              // #490: persist the deferred-tool activation set for the next turn.
+              await persistActivatedTools();
               return;
             }
             const partialChars =
@@ -1729,6 +1967,7 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             await finalizeAssistant(
               flushAssistant(capturedSteps, inProgressText, 'aborted', {
                 pageChanged,
+                partsCache,
               }),
             );
             // #184: settle the RUN as aborted (an explicit user stop reached the
@@ -1739,6 +1978,8 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
             // committed before the client disconnect / stop() must be baked into the
             // snapshot, or the next turn would mis-report it as a user edit.
             await snapshotTurnEnd();
+            // #490: persist the deferred-tool activation set for the next turn.
+            await persistActivatedTools();
           },
         });
 
@@ -2049,6 +2290,70 @@ export function chatStreamMetadata(
   return undefined;
 }
 
+/**
+ * The provider-reported context size of the most recent assistant turn, read from
+ * its persisted `metadata.contextTokens` (#490 replay budgeter's PRIMARY signal —
+ * the provider's own fact, not an estimate). Returns undefined for a chat with no
+ * assistant turn yet, or one whose last turn recorded no usage (e.g. it errored),
+ * in which case the budgeter falls back to the char-estimate.
+ */
+export function lastAssistantContextTokens(
+  history: ReadonlyArray<AiChatMessage>,
+): number | undefined {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const row = history[i];
+    if (row.role !== 'assistant') continue;
+    const meta = (row.metadata ?? {}) as { contextTokens?: unknown };
+    const n = meta.contextTokens;
+    return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Seed the per-turn deferred-tool activation set from a chat's persisted metadata
+ * (#490), INTERSECTED with the current valid deferred names. Persisting the set
+ * across turns saves the model re-running loadTools every turn to re-activate the
+ * same tools; intersecting on load means a changed allowlist / role can never
+ * resurrect a tool that no longer exists (which would hand prepareAgentStep a
+ * phantom active name). Tolerant of any stored shape — a non-array is ignored.
+ */
+export function seedActivatedTools(
+  metadata: Record<string, unknown> | undefined,
+  validDeferredNames: ReadonlySet<string>,
+): string[] {
+  const stored = metadata?.activatedTools;
+  if (!Array.isArray(stored)) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const name of stored) {
+    if (typeof name === 'string' && validDeferredNames.has(name) && !seen.has(name)) {
+      seen.add(name);
+      out.push(name);
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether the most recent assistant turn was rejected for CONTEXT OVERFLOW
+ * (#490): its row carries `metadata.replayOverflow` (stamped by the stream's
+ * onError). The next turn's budgeter reads this to trim aggressively — the
+ * reactive recovery. Only the LAST assistant turn matters (an older overflow was
+ * already recovered), so we stop at the first assistant row scanning backwards.
+ */
+export function lastAssistantReplayOverflow(
+  history: ReadonlyArray<AiChatMessage>,
+): boolean {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const row = history[i];
+    if (row.role !== 'assistant') continue;
+    const meta = (row.metadata ?? {}) as { replayOverflow?: unknown };
+    return meta.replayOverflow === true;
+  }
+  return false;
+}
+
 /** The last message with role 'user' from a useChat payload, if any. */
 function lastUserMessage(
   messages: UIMessage[] | undefined,
@@ -2074,6 +2379,91 @@ function textPart(text: string): Array<{ type: 'text'; text: string }> {
   return text ? [{ type: 'text', text }] : [];
 }
 
+/**
+ * Part types accepted on an INCOMING user turn (#489). The client only ever
+ * sends `sendMessage({ text })` (a single text part); there is no file/attachment
+ * path. Everything else on a client-supplied user message — most dangerously a
+ * tool-part in `input-available` state — is untrusted data that would be
+ * persisted to `metadata.parts` verbatim and replayed through
+ * `convertToModelMessages` on every later turn, potentially bricking the chat.
+ */
+const ALLOWED_USER_PART_TYPES: ReadonlySet<string> = new Set(['text']);
+
+/**
+ * Keep only whitelisted parts on a client-supplied user message; report each
+ * dropped part's type via `onDrop` (the caller warns). Returns `undefined` when
+ * nothing survives (no parts / none whitelisted), so the caller persists a null
+ * metadata rather than an empty-parts object. Never throws.
+ */
+export function sanitizeUserParts(
+  parts: UIMessage['parts'] | undefined,
+  onDrop: (type: string) => void,
+): UIMessage['parts'] | undefined {
+  if (!Array.isArray(parts)) return undefined;
+  const kept = parts.filter((p) => {
+    const type =
+      typeof (p as { type?: unknown })?.type === 'string'
+        ? (p as { type: string }).type
+        : '';
+    if (ALLOWED_USER_PART_TYPES.has(type)) return true;
+    onDrop(type || '(unknown)');
+    return false;
+  });
+  return kept.length > 0 ? (kept as UIMessage['parts']) : undefined;
+}
+
+/** 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
+ * malformed (e.g. a tool-part left unbalanced / in `input-available` state),
+ * which would otherwise 500 every turn of the chat forever. On a batch failure we
+ * fall back to per-row conversion so the bad row is isolated: it is degraded to
+ * plain text carrying its readable text plus a `[tool context omitted]` marker
+ * (the model MUST see that its tool context was truncated — silent loss is not
+ * acceptable), while every healthy row converts normally. Because AI SDK v6
+ * carries a tool call and its result inside the SAME assistant UIMessage's parts,
+ * per-row conversion preserves call/result pairing.
+ */
+export async function convertHistoryResilient(
+  uiMessages: Array<Omit<UIMessage, 'id'> & { id: string }>,
+  onDegrade: (index: number, err: unknown) => void,
+): Promise<ModelMessage[]> {
+  try {
+    return await convertToModelMessages(uiMessages as UIMessage[]);
+  } catch {
+    const out: ModelMessage[] = [];
+    for (let i = 0; i < uiMessages.length; i++) {
+      const m = uiMessages[i];
+      try {
+        out.push(...(await convertToModelMessages([m as UIMessage])));
+      } catch (err) {
+        onDegrade(i, err);
+        const text = uiMessageText(m as UIMessage);
+        const degraded = text
+          ? `${text}\n\n${TOOL_CONTEXT_OMITTED_MARKER}`
+          : TOOL_CONTEXT_OMITTED_MARKER;
+        out.push({
+          role: m.role === 'assistant' ? 'assistant' : 'user',
+          content: degraded,
+        } as ModelMessage);
+      }
+    }
+    return out;
+  }
+}
+
 /**
  * Minimal shapes of the AI SDK v6 step objects we read to rebuild UIMessage
  * parts (see ai@6.0.134 `StepResult`: `text`, `toolCalls` -> TypedToolCall,
@@ -2241,71 +2631,97 @@ function normalizeToolError(error: unknown): string {
  */
 // Exported only so the unit tests can import these pure helpers; exporting
 // them does not change runtime behavior.
+/**
+ * Per-turn memo for {@link assistantParts}: a step's rebuilt parts keyed by the
+ * step OBJECT's identity (#490). A finished step in `capturedSteps` keeps a stable
+ * reference across every mid-stream flush, and `compactToolOutput` inside it does a
+ * `JSON.stringify` of the whole (often 50–200 KB) output — so without a memo each
+ * `onStepFinish` re-stringifies EVERY prior step's output (O(N²) stringify over a
+ * turn). Keyed by step identity => one stringify per step per turn. WeakMap so a
+ * turn's steps are GC'd with the turn.
+ */
+export type StepPartsCache = WeakMap<object, Array<Record<string, unknown>>>;
+
+/** Build the parts for ONE step (text + a part per tool call). Pure. */
+function buildStepParts(step: StepLike): Array<Record<string, unknown>> {
+  const parts: Array<Record<string, unknown>> = [];
+  if (step.text) {
+    parts.push({ type: 'text', text: step.text });
+  }
+  // Index this step's results by tool call id to pair calls with outputs.
+  const resultsById = new Map<string, unknown>();
+  for (const r of step.toolResults ?? []) {
+    if (r.toolCallId) resultsById.set(r.toolCallId, r.output);
+  }
+  // Index this step's THROWN tool failures (ai@6 `tool-error` content parts)
+  // by tool call id, so a call that failed replays with its real error text.
+  const errorsById = new Map<string, unknown>();
+  for (const part of step.content ?? []) {
+    if (part.type === 'tool-error' && part.toolCallId) {
+      errorsById.set(part.toolCallId, part.error);
+    }
+  }
+  for (const call of step.toolCalls ?? []) {
+    if (!call.toolName || !call.toolCallId) continue;
+    const hasResult = resultsById.has(call.toolCallId);
+    if (hasResult) {
+      // output-available: the tool returned; the next turn replays its result.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-available',
+        input: call.input,
+        output: compactToolOutput(resultsById.get(call.toolCallId)),
+      });
+    } else if (errorsById.has(call.toolCallId)) {
+      // The tool THREW: replay the REAL error so the model on the next turn
+      // knows WHY the call failed (and does not blindly repeat it). An
+      // output-error round-trips through convertToModelMessages as a balanced
+      // tool-call + tool-result, keeping the rebuilt history valid.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-error',
+        input: call.input,
+        errorText: normalizeToolError(errorsById.get(call.toolCallId)),
+      });
+    } else {
+      // No paired result AND no tool-error (e.g. aborted mid-step). Persisting
+      // a bare tool-call (input-available) would replay as an unpaired call and
+      // throw MissingToolResultsError on the next turn (convertToModelMessages
+      // emits no tool-result for it). Emit a SYNTHETIC paired result instead:
+      // an output-error round-trips through convertToModelMessages as a
+      // balanced tool-call + tool-result, keeping the rebuilt history valid.
+      parts.push({
+        type: `tool-${call.toolName}`,
+        toolCallId: call.toolCallId,
+        state: 'output-error',
+        input: call.input,
+        errorText: TOOL_CALL_INCOMPLETE_TEXT,
+      });
+    }
+  }
+  return parts;
+}
+
 export function assistantParts(
   steps: ReadonlyArray<StepLike> | undefined,
   fallbackText: string,
+  cache?: StepPartsCache,
 ): UIMessage['parts'] {
   const parts: Array<Record<string, unknown>> = [];
-  let sawText = false;
   for (const step of steps ?? []) {
-    if (step.text) {
-      parts.push({ type: 'text', text: step.text });
-      sawText = true;
-    }
-    // Index this step's results by tool call id to pair calls with outputs.
-    const resultsById = new Map<string, unknown>();
-    for (const r of step.toolResults ?? []) {
-      if (r.toolCallId) resultsById.set(r.toolCallId, r.output);
-    }
-    // Index this step's THROWN tool failures (ai@6 `tool-error` content parts)
-    // by tool call id, so a call that failed replays with its real error text.
-    const errorsById = new Map<string, unknown>();
-    for (const part of step.content ?? []) {
-      if (part.type === 'tool-error' && part.toolCallId) {
-        errorsById.set(part.toolCallId, part.error);
-      }
-    }
-    for (const call of step.toolCalls ?? []) {
-      if (!call.toolName || !call.toolCallId) continue;
-      const hasResult = resultsById.has(call.toolCallId);
-      if (hasResult) {
-        // output-available: the tool returned; the next turn replays its result.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-available',
-          input: call.input,
-          output: compactToolOutput(resultsById.get(call.toolCallId)),
-        });
-      } else if (errorsById.has(call.toolCallId)) {
-        // The tool THREW: replay the REAL error so the model on the next turn
-        // knows WHY the call failed (and does not blindly repeat it). An
-        // output-error round-trips through convertToModelMessages as a balanced
-        // tool-call + tool-result, keeping the rebuilt history valid.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-error',
-          input: call.input,
-          errorText: normalizeToolError(errorsById.get(call.toolCallId)),
-        });
-      } else {
-        // No paired result AND no tool-error (e.g. aborted mid-step). Persisting
-        // a bare tool-call (input-available) would replay as an unpaired call and
-        // throw MissingToolResultsError on the next turn (convertToModelMessages
-        // emits no tool-result for it). Emit a SYNTHETIC paired result instead:
-        // an output-error round-trips through convertToModelMessages as a
-        // balanced tool-call + tool-result, keeping the rebuilt history valid.
-        parts.push({
-          type: `tool-${call.toolName}`,
-          toolCallId: call.toolCallId,
-          state: 'output-error',
-          input: call.input,
-          errorText: 'Tool call did not complete.',
-        });
-      }
+    // Memoize per step object (#490): a finished step is immutable and keeps its
+    // reference across flushes, so its parts (and the costly output stringify) are
+    // built exactly once per turn. A cache miss (or no cache) just rebuilds.
+    let stepParts = cache?.get(step as object);
+    if (!stepParts) {
+      stepParts = buildStepParts(step);
+      cache?.set(step as object, stepParts);
     }
+    parts.push(...stepParts);
   }
+  const sawText = parts.some((p) => p.type === 'text');
   if (!sawText && fallbackText) {
     // No per-step text (e.g. a single final block): append the final text after
     // any tool parts so the natural call -> result -> answer order is preserved.
@@ -2468,6 +2884,16 @@ export function flushAssistant(
     maxContextTokens?: number;
     error?: string;
     pageChanged?: { title: string; diff: string } | null;
+    // Per-turn step->parts memo (#490): pass the SAME cache on every flush of a
+    // turn so each finished step's output is stringified once, not once per flush.
+    partsCache?: StepPartsCache;
+    // #490 observability: when the replay budgeter trimmed this turn's history,
+    // the (estimated) token size it trimmed to — the UI can show "replay truncated
+    // at N tokens". Omitted when nothing was trimmed.
+    replayTrimmedToTokens?: number;
+    // #490 reactive branch: set when the provider rejected this turn for context
+    // overflow. Stamped into metadata so the NEXT turn's budgeter trims aggressively.
+    replayOverflow?: boolean;
   },
 ): AssistantFlush {
   const finished = capturedSteps ?? [];
@@ -2477,13 +2903,32 @@ export function flushAssistant(
   // in-progress step's text (the partial answer cut off by an error/abort, or
   // simply not yet flushed mid-stream) as the last text part so the persisted
   // parts match what streamed to the client.
-  const parts = assistantParts(finished, '') as unknown as Array<
-    Record<string, unknown>
-  >;
+  const parts = assistantParts(
+    finished,
+    '',
+    extra?.partsCache,
+  ) as unknown as Array<Record<string, unknown>>;
   if (trailing) parts.push({ type: 'text', text: trailing });
 
   const metadata: Record<string, unknown> = {
     parts: parts as unknown as UIMessage['parts'],
+    // Era marker for the `tool_calls` trace shape (#490): v2 stores outcome flags
+    // ({ ok } / { error, kind }) and NO tool output (the output lives once in
+    // `parts`). Old rows have no marker and the legacy { output } shape; a
+    // dual-shape query branches on this. Old rows are deliberately NOT migrated.
+    toolTraceVersion: 2,
+    // #491 STEP MARKER: the number of FINISHED steps whose parts are in THIS row,
+    // written by the SAME flush that builds `parts` (atomically — they are both
+    // derived from `finished`, so the marker can NEVER disagree with the persisted
+    // parts). This is the step-alignment anchor the resume stack builds on:
+    // - the registry rotates its retention ring only on a CONFIRMED persist of
+    //   step N (commit 3);
+    // - attach slices the tail at "step > N" from the client's persisted seed.
+    // It is NOT `run.stepCount`: recordStep is fire-and-forget and NOT atomic with
+    // the parts write, so stepCount could race ahead of the persisted parts
+    // (seed↔marker drift). The in-progress trailing text (an error/abort partial,
+    // or a mid-stream flush) is NOT a finished step and is excluded from the count.
+    stepsPersisted: finished.length,
   };
   // finishReason: prefer an explicit one; else derive a sensible value from the
   // terminal status (so onError/onAbort records keep their historical reason).
@@ -2499,6 +2944,9 @@ export function flushAssistant(
   if (extra?.contextTokens) metadata.contextTokens = extra.contextTokens;
   if (extra?.maxContextTokens)
     metadata.maxContextTokens = extra.maxContextTokens;
+  if (extra?.replayTrimmedToTokens)
+    metadata.replayTrimmedToTokens = extra.replayTrimmedToTokens;
+  if (extra?.replayOverflow) metadata.replayOverflow = true;
   if (extra?.error) metadata.error = extra.error;
   // Persist the page-change diff the agent saw this turn (#274 observability),
   // so history / the Markdown export can show what the user changed. Only when
@@ -2524,42 +2972,85 @@ export function flushAssistant(
 
 /**
  * Reduce SDK step objects to a compact, JSON-serializable trace for the
- * `tool_calls` column. Stores only what the UI action-log and history need —
- * never raw provider payloads or keys.
+ * `tool_calls` column — trace format **v2** (#490).
+ *
+ * v2 stores, per call, ONLY the metadata a queryable trace needs — never the
+ * tool OUTPUT. Before #490 each output was persisted TWICE: once here (compacted)
+ * and once in `metadata.parts` (via `assistantParts`), so a 50-step run with
+ * 50–200 KB outputs wrote hundreds of MB per turn (each `onStepFinish` rewrote
+ * the whole row). The parts copy is the one the model replays and the UI/Markdown
+ * export render, so the trace copy of the output was pure duplication. v2 keeps
+ * the output ONLY in parts and reduces the trace to outcome flags.
+ *
+ * Element shapes (paired per call, in order):
+ *  - `{ toolName, input }`                       — the call
+ *  - `{ toolName, ok: true }`                     — it returned a result (success)
+ *  - `{ toolName, error, kind: 'thrown' }`        — it threw a `tool-error`
+ *  - `{ toolName, error, kind: 'interrupted' }`   — no result and no throw (an
+ *      abort / server restart mid-step). `kind` is MANDATORY: without it a
+ *      synthetic "Tool call did not complete." is indistinguishable from a real
+ *      hard-fail and pollutes any error-rate scan. The distinction is STRUCTURAL
+ *      (an `errorsById` hit vs the synthetic fallback branch), NOT a per-tool
+ *      classifier — soft failures stay OUT of the trace (they live in
+ *      `metadata.parts` outputs; a per-tool mirror would persist its own bugs).
+ *
+ * Rows carry `metadata.toolTraceVersion: 2` (set by {@link flushAssistant}) so a
+ * dual-shape query can branch on the era. Old rows are NOT migrated (rewriting
+ * giant jsonb is the very WAL churn this removes); see docs/reading-ai-logs.md.
  */
 export function serializeSteps(
   steps: ReadonlyArray<{
-    toolCalls?: ReadonlyArray<{ toolName?: string; input?: unknown }>;
-    toolResults?: ReadonlyArray<{ toolName?: string; output?: unknown }>;
+    toolCalls?: ReadonlyArray<{
+      toolCallId?: string;
+      toolName?: string;
+      input?: unknown;
+    }>;
+    toolResults?: ReadonlyArray<{ toolCallId?: string; toolName?: string }>;
     content?: ReadonlyArray<{
       type?: string;
+      toolCallId?: string;
       toolName?: string;
       error?: unknown;
     }>;
   }>,
 ): unknown {
-  const calls: Array<{
-    toolName?: string;
-    input?: unknown;
-    output?: unknown;
-    error?: string;
-  }> = [];
+  const calls: Array<
+    | { toolName?: string; input?: unknown }
+    | { toolName?: string; ok: true }
+    | { toolName?: string; error: string; kind: 'thrown' | 'interrupted' }
+  > = [];
   for (const step of steps ?? []) {
+    // Index this step's results + thrown errors by tool call id, so each call is
+    // paired with its outcome (mirrors assistantParts' pairing exactly).
+    const resultIds = new Set<string>();
+    for (const r of step.toolResults ?? []) {
+      if (r.toolCallId) resultIds.add(r.toolCallId);
+    }
+    const errorsById = new Map<string, unknown>();
+    for (const part of step.content ?? []) {
+      if (part.type === 'tool-error' && part.toolCallId) {
+        errorsById.set(part.toolCallId, part.error);
+      }
+    }
     for (const call of step.toolCalls ?? []) {
       calls.push({ toolName: call.toolName, input: call.input });
-    }
-    for (const r of step.toolResults ?? []) {
-      calls.push({ toolName: r.toolName, output: compactToolOutput(r.output) });
-    }
-    // ai@6 surfaces a THROWN tool failure as a `tool-error` content part, NOT as
-    // a `toolResults` entry. Record it as its own paired element (mirroring how a
-    // successful result is appended) so the failure and its reason survive in the
-    // trace instead of leaving an orphaned call with no result.
-    for (const part of step.content ?? []) {
-      if (part.type === 'tool-error') {
+      if (call.toolCallId && resultIds.has(call.toolCallId)) {
+        // Success: the output itself lives in metadata.parts, not here.
+        calls.push({ toolName: call.toolName, ok: true });
+      } else if (call.toolCallId && errorsById.has(call.toolCallId)) {
+        // Hard fail: the tool threw. Persist the real (bounded) reason.
         calls.push({
-          toolName: part.toolName,
-          error: normalizeToolError(part.error),
+          toolName: call.toolName,
+          error: normalizeToolError(errorsById.get(call.toolCallId)),
+          kind: 'thrown',
+        });
+      } else {
+        // Neither a result nor a throw: interrupted mid-step (abort/restart).
+        // Marked structurally so it never inflates a thrown-error count.
+        calls.push({
+          toolName: call.toolName,
+          error: TOOL_CALL_INCOMPLETE_TEXT,
+          kind: 'interrupted',
         });
       }
     }

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

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

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

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

apps/server/src/core/ai-chat/chat-markdown.util.spec.ts

@@ -1,5 +1,10 @@
-import { buildChatMarkdown, normalizeLang } from './chat-markdown.util';
+import {
+  buildChatMarkdown,
+  normalizeLang,
+  labelledToolNames,
+} from './chat-markdown.util';
 import type { AiChatMessage } from '@docmost/db/types/entity.types';
+import { SHARED_TOOL_SPECS } from '../../../../../packages/mcp/src/tool-specs';
 
 /**
  * normalizeLang: the client sends `i18n.language` — a FULL locale tag like
@@ -455,3 +460,43 @@ describe('buildChatMarkdown (server) — structure', () => {
     expect(md).toContain('````');
   });
 });
+
+/**
+ * #494 — REVERSE drift-guard for the export's friendly tool labels. A label keyed
+ * by a tool name that no longer exists silently degrades to the generic
+ * "Ran tool <name>" line; nothing reddened before. This asserts every labelled
+ * name is a real in-app tool and that both languages label the same set.
+ */
+describe('tool-label parity (#494)', () => {
+  // In-app tool names come from the shared registry (inAppKey, excluding
+  // mcpOnly specs) PLUS the inline in-app-only tools that carry a friendly label.
+  // The only labelled inline tool is the hybrid semantic search.
+  const INLINE_INAPP_LABELLED = new Set(['searchPages']);
+
+  function validInAppToolNames(): Set<string> {
+    const names = new Set<string>(INLINE_INAPP_LABELLED);
+    for (const spec of Object.values(SHARED_TOOL_SPECS)) {
+      if ((spec as { mcpOnly?: boolean }).mcpOnly) continue;
+      names.add((spec as { inAppKey: string }).inAppKey);
+    }
+    return names;
+  }
+
+  it('en and ru label the SAME set of tools', () => {
+    expect(labelledToolNames('en').sort()).toEqual(
+      labelledToolNames('ru').sort(),
+    );
+  });
+
+  it('every labelled tool name is a real in-app tool', () => {
+    const valid = validInAppToolNames();
+    const dead = labelledToolNames('en').filter((n) => !valid.has(n));
+    expect(dead).toEqual([]);
+  });
+
+  it('the guard REDDENS for an unknown label key (mutation check)', () => {
+    const valid = validInAppToolNames();
+    // A hypothetical renamed-away label must be caught.
+    expect(valid.has('getPageRenamedAway')).toBe(false);
+  });
+});

apps/server/src/core/ai-chat/chat-markdown.util.ts

@@ -154,6 +154,17 @@ function toolLabel(name: string, lang: ExportLang): string {
   return LABELS[lang].tools[name] ?? LABELS[lang].ranTool(name);
 }
 
+/**
+ * The tool names that carry a hand-written friendly export label, per language.
+ * Exported for the drift-guard (#494): a label keyed by a tool name that no
+ * longer exists is a DEAD entry (the tool was renamed and now silently falls back
+ * to the generic `ranTool(name)` line). The guard asserts every key here is a
+ * real in-app tool AND that the two languages label the SAME set of tools.
+ */
+export function labelledToolNames(lang: ExportLang): string[] {
+  return Object.keys(LABELS[lang].tools);
+}
+
 /**
  * Stringify an arbitrary tool input/output value for a fenced block. Strings
  * pass through as-is; everything else is pretty-printed JSON, falling back to

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

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

apps/server/src/core/ai-chat/external-mcp/dto/create-mcp-server.dto.ts

@@ -37,10 +37,13 @@ export class CreateMcpServerDto {
   @IsObject()
   headers?: Record<string, string>;
 
+  // Omit/null => no restriction; `[]` is persisted verbatim and means deny-all
+  // (zero tools) since #476. @IsOptional() skips validation for null as well,
+  // so an explicit null is accepted.
   @IsOptional()
   @IsArray()
   @IsString({ each: true })
-  toolAllowlist?: string[];
+  toolAllowlist?: string[] | null;
 
   // Admin-authored guidance ("how/when to use this server's tools") injected
   // into the agent system prompt next to the tool descriptions (#180). Trusted,

apps/server/src/core/ai-chat/external-mcp/dto/update-mcp-server.dto.ts

@@ -38,10 +38,13 @@ export class UpdateMcpServerDto {
   @IsObject()
   headers?: Record<string, string>;
 
+  // Absent => unchanged; null => no restriction; `[]` is persisted verbatim
+  // and means deny-all (zero tools) since #476. @IsOptional() skips validation
+  // for null as well, so an explicit null is accepted.
   @IsOptional()
   @IsArray()
   @IsString({ each: true })
-  toolAllowlist?: string[];
+  toolAllowlist?: string[] | null;
 
   // Admin-authored prompt guidance (#180). Absent => unchanged; blank => cleared
   // (stored as null by the repo). Capped to bound prompt/token size.

apps/server/src/core/ai-chat/external-mcp/mcp-allowlist-filter.spec.ts

@@ -0,0 +1,169 @@
+import { type Tool } from 'ai';
+import { McpClientsService } from './mcp-clients.service';
+
+/**
+ * Tool-allowlist filtering semantics on the merged external toolset (#476).
+ *
+ * COVERAGE CHOICE (documented per issue #476): the full corrupt-row chain
+ * (DB value -> repo normalizeRow -> toolsFor filter) is covered on TWO levels
+ * instead of one live-stub-MCP-server integration test:
+ *   (a) apps/server/test/integration/ai-mcp-server-repo.int-spec.ts pins the
+ *       repo read/write semantics against a real Postgres — `[]` round-trips
+ *       as jsonb `[]`, a present-but-corrupt value fails CLOSED to `[]` with
+ *       an error log;
+ *   (b) THIS spec pins what the toolset builder does with the repo's output —
+ *       null = unrestricted, `['alpha']` = only alpha, `[]` (including the
+ *       corrupt-row fallback) = ZERO tools.
+ * Together they prove the end-to-end property "corrupt/empty allowlist can
+ * never widen to all tools" without a live stub HTTP MCP server.
+ *
+ * The drive path mirrors mcp-namespacing.spec.ts: stub the repo's listEnabled,
+ * spy the private `connect` to return a fake client, inspect the merged keys.
+ */
+
+function fakeTool(): Tool {
+  return { description: 'x', inputSchema: undefined } as unknown as Tool;
+}
+
+interface FakeServer {
+  id: string;
+  name: string;
+  transport: string;
+  url: string;
+  headersEnc: string | null;
+  toolAllowlist: string[] | null;
+}
+
+function server(
+  over: Partial<FakeServer> & { id: string; name: string },
+): FakeServer {
+  return {
+    transport: 'http',
+    url: 'https://example.com/mcp',
+    headersEnc: null,
+    toolAllowlist: null,
+    ...over,
+  };
+}
+
+/**
+ * Build a service whose repo returns `servers` and whose fake clients expose
+ * `rawTools` from tools(). Returns the merged tool keys produced by toolsFor.
+ */
+async function mergedKeysFor(
+  servers: FakeServer[],
+  rawTools: Record<string, Tool>,
+): Promise<string[]> {
+  const repoStub = {
+    listEnabled: jest.fn().mockResolvedValue(servers),
+  };
+  const service = new McpClientsService(repoStub as never, {} as never);
+
+  jest
+    .spyOn(
+      service as unknown as { connect: (s: FakeServer) => unknown },
+      'connect',
+    )
+    .mockImplementation(() =>
+      Promise.resolve({
+        tools: () => Promise.resolve(rawTools),
+        close: () => Promise.resolve(),
+      }),
+    );
+
+  const toolset = await service.toolsFor('ws-1');
+  // Release the lease so the service does not hold the fake clients open.
+  await Promise.all(toolset.clients.map((c) => c.close()));
+  return Object.keys(toolset.tools);
+}
+
+describe('external MCP tool-allowlist filtering (via toolsFor, #476)', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  const RAW = () => ({
+    alpha: fakeTool(),
+    beta: fakeTool(),
+    gamma: fakeTool(),
+  });
+
+  it("['alpha'] lets ONLY alpha through", async () => {
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: ['alpha'] })],
+      RAW(),
+    );
+    expect(keys).toEqual(['srv_alpha']);
+  });
+
+  it('null (no restriction) lets every tool through', async () => {
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: null })],
+      RAW(),
+    );
+    expect(keys.sort()).toEqual(['srv_alpha', 'srv_beta', 'srv_gamma']);
+  });
+
+  it('[] (deny-all) yields ZERO tools — an empty array is authoritative, not falsy (#476)', async () => {
+    // This is the regression the #476 change guards: `[]` used to fall through
+    // the old `allow.length > 0` check and expose ALL tools. It must expose NONE.
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: [] })],
+      RAW(),
+    );
+    expect(keys).toEqual([]);
+  });
+
+  it('the corrupt-row fallback ([] from the repo) also yields ZERO tools (#476)', async () => {
+    // The repo turns a present-but-corrupt tool_allowlist into `[]` (fail-closed,
+    // see normalizeRow in ai-mcp-server.repo.ts + the int-spec); this pins that
+    // the toolset builder honours that fallback as deny-all rather than allow-all.
+    const corruptFallback: string[] = [];
+    const keys = await mergedKeysFor(
+      [server({ id: 'id-1', name: 'srv', toolAllowlist: corruptFallback })],
+      RAW(),
+    );
+    expect(keys).toEqual([]);
+  });
+
+  it('allowlisted names not exposed by the server are ignored (no phantom tools)', async () => {
+    const keys = await mergedKeysFor(
+      [
+        server({
+          id: 'id-1',
+          name: 'srv',
+          toolAllowlist: ['alpha', 'does-not-exist'],
+        }),
+      ],
+      RAW(),
+    );
+    expect(keys).toEqual(['srv_alpha']);
+  });
+
+  it('a deny-all server contributes no prompt instructions (0 tools merged)', async () => {
+    const repoStub = {
+      listEnabled: jest.fn().mockResolvedValue([
+        {
+          ...server({ id: 'id-1', name: 'srv', toolAllowlist: [] }),
+          instructions: 'use the tools wisely',
+        },
+      ]),
+    };
+    const service = new McpClientsService(repoStub as never, {} as never);
+    jest
+      .spyOn(
+        service as unknown as { connect: (s: FakeServer) => unknown },
+        'connect',
+      )
+      .mockImplementation(() =>
+        Promise.resolve({
+          tools: () => Promise.resolve(RAW()),
+          close: () => Promise.resolve(),
+        }),
+      );
+
+    const toolset = await service.toolsFor('ws-1');
+    await Promise.all(toolset.clients.map((c) => c.close()));
+    expect(Object.keys(toolset.tools)).toEqual([]);
+    // mergeNamespaced reported 0 contributed tools, so no guidance is attached.
+    expect(toolset.instructions).toEqual([]);
+  });
+});

apps/server/src/core/ai-chat/external-mcp/mcp-clients.recovery.spec.ts

@@ -0,0 +1,261 @@
+import { errors } from 'undici';
+import {
+  McpClientsService,
+  isRetryableConnectError,
+} from './mcp-clients.service';
+
+/**
+ * #489 — external-MCP in-run transport recovery.
+ *
+ * The transport-error classification + retry gate are exercised against the REAL
+ * undici error CLASSES prod throws (`errors.SocketError` / `errors.BodyTimeoutError`,
+ * carrying the true `UND_ERR_*` codes and class names), wrapped EXACTLY as undici's
+ * `fetch` wraps them — a `TypeError('fetch failed'|'terminated')` whose `.cause` is
+ * the undici error. These are the real classes, not hand-rolled `{code:'...'}`
+ * mocks: constructing the genuine class is what makes this a faithful test of the
+ * prod predicate (epic root-cause #4 — a mock-shaped predicate would leave the
+ * evict/retry path silently dead in production while CI stays green). We construct
+ * rather than drive a live fetch because Jest's environment degrades the live-fetch
+ * error to a generic `Error` cause (no undici code), which would NOT be the prod
+ * shape.
+ */
+
+/** A REAL undici socket reset, wrapped as fetch wraps it. */
+function realSocketResetError(): unknown {
+  const err = new TypeError('fetch failed');
+  (err as { cause?: unknown }).cause = new errors.SocketError('other side closed');
+  return err;
+}
+
+/** A REAL undici body timeout, wrapped as fetch wraps it. */
+function realBodyTimeoutError(): unknown {
+  const err = new TypeError('terminated');
+  (err as { cause?: unknown }).cause = new errors.BodyTimeoutError();
+  return err;
+}
+
+type FakeServer = {
+  id: string;
+  name: string;
+  transport: 'http' | 'sse';
+  url: string;
+  headersEnc: string | null;
+  toolAllowlist: string[] | null;
+  instructions: string | null;
+};
+
+const server = (over: Partial<FakeServer> = {}): FakeServer => ({
+  id: 's1',
+  name: 'srv',
+  transport: 'http',
+  url: 'http://example.test/mcp',
+  headersEnc: null,
+  toolAllowlist: null,
+  instructions: null,
+  ...over,
+});
+
+function buildService(servers: FakeServer[], trusted = false) {
+  const repo = { listEnabled: jest.fn().mockResolvedValue(servers) };
+  const service = new McpClientsService(repo as never, {} as never);
+  // Seed a DETERMINISTIC write-class map so the retry gate is controlled here
+  // (the production map loads from @docmost/mcp via a dynamic ESM import). getPage
+  // is a read, patchNode is a write — the real classifications.
+  (
+    service as unknown as { writeClassMapPromise: Promise<unknown> }
+  ).writeClassMapPromise = Promise.resolve({
+    getPage: 'readOnly',
+    patchNode: 'write',
+  });
+  // The service only APPLIES that map to a TRUSTED internal Docmost server
+  // (isInternalDocmostServer, really false for every third-party row). A retry
+  // test needs a trusted server to exercise the readOnly-retry path at all, so it
+  // passes trusted=true to model a Docmost-origin server; the third-party
+  // double-apply test leaves it at the real value (false).
+  if (trusted) {
+    jest
+      .spyOn(
+        service as unknown as {
+          isInternalDocmostServer: (s: FakeServer) => boolean;
+        },
+        'isInternalDocmostServer',
+      )
+      .mockReturnValue(true);
+  }
+  return { service, repo };
+}
+
+/** Spy the private `connect` so each call yields a controlled fake client whose
+ *  single tool's execute is the supplied function. Returns the connect spy. */
+function stubConnect(
+  service: McpClientsService,
+  toolName: string,
+  execs: Array<(...a: unknown[]) => Promise<unknown>>,
+) {
+  let n = 0;
+  return jest
+    .spyOn(
+      service as unknown as { connect: (s: FakeServer) => Promise<unknown> },
+      'connect',
+    )
+    .mockImplementation(async () => {
+      const exec = execs[Math.min(n, execs.length - 1)];
+      n += 1;
+      return {
+        tools: async () => ({ [toolName]: { description: 'x', execute: exec } }),
+        close: jest.fn().mockResolvedValue(undefined),
+      };
+    });
+}
+
+const opts = (abortSignal?: AbortSignal) =>
+  ({ toolCallId: 't', messages: [], abortSignal }) as never;
+
+describe('isRetryableConnectError (#489, REAL error shapes)', () => {
+  it('classifies a real undici socket reset and body timeout as retryable', async () => {
+    const socketErr = await realSocketResetError();
+    const bodyErr = await realBodyTimeoutError();
+    expect(isRetryableConnectError(socketErr)).toBe(true);
+    expect(isRetryableConnectError(bodyErr)).toBe(true);
+    // Unwraps a wrapped cause chain (e.g. an MCPClientError around the socket err).
+    const wrapped = new Error('mcp call failed');
+    (wrapped as { cause?: unknown }).cause = socketErr;
+    expect(isRetryableConnectError(wrapped)).toBe(true);
+  });
+
+  it('does NOT classify an application-level error as a transport break', () => {
+    expect(isRetryableConnectError(new Error('validation failed'))).toBe(false);
+    expect(isRetryableConnectError({ name: 'HttpError', status: 400 })).toBe(false);
+    expect(isRetryableConnectError(undefined)).toBe(false);
+    expect(isRetryableConnectError('boom')).toBe(false);
+  });
+});
+
+describe('McpClientsService in-run transport recovery (#489)', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('a readOnly tool whose transport breaks reconnects and retries WITHIN the same run', async () => {
+    const realErr = await realSocketResetError();
+    const { service } = buildService([server()], true);
+    const first = jest.fn().mockRejectedValue(realErr);
+    const second = jest.fn().mockResolvedValue({ ok: true });
+    const connectSpy = stubConnect(service, 'getPage', [first, second]);
+
+    const toolset = await service.toolsFor('ws-1');
+    const tool = toolset.tools['srv_getPage'];
+    const result = await (tool.execute as (a: unknown, o: unknown) => Promise<unknown>)(
+      { pageId: 'p' },
+      opts(),
+    );
+
+    // The repeat call within the run got a LIVE client and succeeded.
+    expect(result).toEqual({ ok: true });
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+    // Exactly one reconnect was minted (initial build connect + one recovery).
+    expect(connectSpy).toHaveBeenCalledTimes(2);
+    // The run accumulated BOTH leases (old + reconnected) — released together at end.
+    expect(toolset.clients).toHaveLength(2);
+    await Promise.all(toolset.clients.map((c) => c.close()));
+  });
+
+  it('a WRITE tool does NOT auto-retry on a transport error (indeterminate)', async () => {
+    const realErr = await realSocketResetError();
+    const { service } = buildService([server()], true);
+    const exec = jest.fn().mockRejectedValue(realErr);
+    const connectSpy = stubConnect(service, 'patchNode', [exec]);
+
+    const toolset = await service.toolsFor('ws-2');
+    const tool = toolset.tools['srv_patchNode'];
+    await expect(
+      (tool.execute as (a: unknown, o: unknown) => Promise<unknown>)(
+        { pageId: 'p' },
+        opts(),
+      ),
+    ).rejects.toThrow(/MAY have already applied/);
+
+    // Called exactly once — NO blind retry (avoids double-apply, the #435 class).
+    expect(exec).toHaveBeenCalledTimes(1);
+    // No fresh connection was minted for a write.
+    expect(connectSpy).toHaveBeenCalledTimes(1);
+    await Promise.all(toolset.clients.map((c) => c.close()));
+  });
+
+  it('does NOT retry (or reconnect) after the run is aborted (Stop)', async () => {
+    const realErr = await realSocketResetError();
+    const { service } = buildService([server()], true);
+    const controller = new AbortController();
+    // The transport error arrives, but the run was Stopped in the same tick.
+    const first = jest.fn().mockImplementation(async () => {
+      controller.abort();
+      throw realErr;
+    });
+    const second = jest.fn().mockResolvedValue({ ok: true });
+    const connectSpy = stubConnect(service, 'getPage', [first, second]);
+
+    const toolset = await service.toolsFor('ws-3');
+    const tool = toolset.tools['srv_getPage'];
+    await expect(
+      (tool.execute as (a: unknown, o: unknown) => Promise<unknown>)(
+        { pageId: 'p' },
+        opts(controller.signal),
+      ),
+    ).rejects.toBeDefined();
+
+    // getPage IS readOnly, but the Stop blocks the retry — no second call, no mint.
+    expect(second).not.toHaveBeenCalled();
+    expect(connectSpy).toHaveBeenCalledTimes(1);
+    await Promise.all(toolset.clients.map((c) => c.close()));
+  });
+
+  it('an app-level (non-transport) tool error is surfaced verbatim, never retried', async () => {
+    const { service } = buildService([server()], true);
+    const appErr = new Error('tool says: bad input');
+    const exec = jest.fn().mockRejectedValue(appErr);
+    const connectSpy = stubConnect(service, 'getPage', [exec]);
+
+    const toolset = await service.toolsFor('ws-4');
+    const tool = toolset.tools['srv_getPage'];
+    await expect(
+      (tool.execute as (a: unknown, o: unknown) => Promise<unknown>)(
+        { pageId: 'p' },
+        opts(),
+      ),
+    ).rejects.toThrow('tool says: bad input');
+    expect(exec).toHaveBeenCalledTimes(1);
+    expect(connectSpy).toHaveBeenCalledTimes(1); // no reconnect for an app error
+    await Promise.all(toolset.clients.map((c) => c.close()));
+  });
+
+  // #489 (review, MEDIUM) — the Docmost write-class map keys by DOCMOST tool
+  // names; a THIRD-PARTY server may name a WRITE tool `getPage` (a Docmost read
+  // name). It must NOT inherit readOnly and must NOT auto-retry on a transport
+  // error — a blind retry of that write is a double-apply (the #435 class). Here
+  // the server is UNTRUSTED (buildService default, isInternalDocmostServer=false),
+  // so the map is not applied and `getPage` classifies as a write.
+  //
+  // MUTATION-VERIFY: forcing the server "trusted" (buildService(..., true)) makes
+  // `getPage` inherit readOnly -> it WOULD reconnect+retry (connect twice) and the
+  // assertions below fail — i.e. removing the trust scope re-opens the bug.
+  it('a THIRD-PARTY WRITE tool named like a Docmost read does NOT auto-retry (no double-apply)', async () => {
+    const realErr = await realSocketResetError();
+    // Untrusted: default trusted=false — a real third-party server.
+    const { service } = buildService([server()]);
+    const exec = jest.fn().mockRejectedValue(realErr);
+    const connectSpy = stubConnect(service, 'getPage', [exec, exec]);
+
+    const toolset = await service.toolsFor('ws-5');
+    const tool = toolset.tools['srv_getPage'];
+    await expect(
+      (tool.execute as (a: unknown, o: unknown) => Promise<unknown>)(
+        { pageId: 'p' },
+        opts(),
+      ),
+    ).rejects.toThrow(/MAY have already applied/);
+
+    // Exactly one call, NO reconnect — the name collision granted no readOnly-retry.
+    expect(exec).toHaveBeenCalledTimes(1);
+    expect(connectSpy).toHaveBeenCalledTimes(1);
+    await Promise.all(toolset.clients.map((c) => c.close()));
+  });
+});

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

@@ -106,8 +106,11 @@ describe('McpClientsService.decryptHeaders', () => {
 
 describe('McpClientsService.guardedFetch (SSRF per-request guard)', () => {
   // The bound guardedFetch closure lives on the instance as a private field.
+  // #489 split it into per-transport HTTP/SSE bindings (they differ only in the
+  // dispatcher's bodyTimeout); the SSRF guard is identical, so testing the HTTP
+  // one is sufficient.
   const guardedFetchOf = (service: McpClientsService) =>
-    (service as unknown as { guardedFetch: typeof fetch }).guardedFetch;
+    (service as unknown as { guardedFetchHttp: typeof fetch }).guardedFetchHttp;
 
   let fetchSpy: jest.SpiedFunction<typeof fetch>;
 

apps/server/src/core/ai-chat/external-mcp/mcp-clients.service.ts

@@ -1,5 +1,6 @@
 import { isIP } from 'node:net';
 import { lookup as dnsLookup, type LookupAddress } from 'node:dns';
+import { pathToFileURL } from 'node:url';
 import { Injectable, Logger } from '@nestjs/common';
 import { type Tool, type ToolCallOptions } from 'ai';
 import { createMCPClient } from '@ai-sdk/mcp';
@@ -10,9 +11,29 @@ import {
   streamingDispatcherOptions,
   mcpStreamTimeoutMs,
   mcpCallTimeoutMs,
+  mcpSseBodyTimeoutMs,
 } from '../../../integrations/ai/ai-streaming-fetch';
 import { SecretBoxService } from '../../../integrations/crypto/secret-box';
 import { isUrlAllowed, isIpAllowed } from './ssrf-guard';
+// TYPE-ONLY (erased at compile): @docmost/mcp is ESM-only and cannot be a runtime
+// `require()` from this commonjs module (same constraint as docmost-client.loader).
+// The write-class MAP is loaded lazily via the dynamic-import trick below.
+import type { ToolWriteClass } from '@docmost/mcp';
+
+// TS(commonjs) downlevels a literal `import()` to `require()`, which cannot load
+// the ESM-only @docmost/mcp. Indirect through Function so the real dynamic
+// `import()` survives compilation (same trick as docmost-client.loader.ts).
+const esmImport = new Function(
+  'specifier',
+  'return import(specifier)',
+) as (specifier: string) => Promise<unknown>;
+
+/** Local read-only predicate — avoids a value import of the ESM-only package.
+ *  Only a pure read is retry-safe after a transport break (a write is
+ *  indeterminate). Kept in lockstep with @docmost/mcp's isRetryableWriteClass. */
+function isReadOnlyWriteClass(writeClass: ToolWriteClass | undefined): boolean {
+  return writeClass === 'readOnly';
+}
 
 /** A closable external MCP client handle. */
 export interface Closable {
@@ -81,12 +102,52 @@ const MAX_TOOL_NAME_LENGTH = 64;
  * close until the turn releases it, so a TTL expiry mid-turn never closes a
  * client a stream is still executing against.
  */
+/**
+ * Where a merged (namespaced) tool came from, so the per-run recovery wrapper
+ * (#489) can, on a transport error, reconnect THAT server and re-resolve the SAME
+ * underlying tool by its raw name. `writeClass` gates the single auto-retry (a
+ * read is retry-safe; a write is indeterminate). `serverIndex` indexes the
+ * entry's `servers` array (which server config to reconnect).
+ */
+interface ToolProvenance {
+  serverIndex: number;
+  rawName: string;
+  writeClass: ToolWriteClass | undefined;
+}
+
+/** A live reconnected server (its fresh client + raw call-timeout-wrapped tools). */
+interface RecoveredServerState {
+  client: McpClient;
+  tools: Record<string, Tool>;
+}
+
+/**
+ * Per-run, per-server recovery binding (#489). `current` is the server's LIVE
+ * target for this run: `null` means "use the ORIGINAL cached client/template";
+ * a non-null value is a reconnected throwaway client all this server's tools now
+ * call. `reconnecting` dedupes concurrent reconnects so only ONE fresh client is
+ * minted per death (a losing concurrent call awaits it and retries on the SAME
+ * new client — the CAS-by-identity rule).
+ */
+interface ServerBinding {
+  current: RecoveredServerState | null;
+  reconnecting?: Promise<RecoveredServerState>;
+}
+
 interface CacheEntry {
   tools: Record<string, Tool>;
   clients: McpClient[];
   outcomes: ServerOutcome[];
   /** Prompt guidance for qualifying servers (see McpServerInstruction). */
   instructions: McpServerInstruction[];
+  /**
+   * The enabled server configs used to build this entry (#489), so the per-run
+   * recovery wrapper can reconnect a specific server by index. Parallel to the
+   * indices referenced by {@link toolMeta}.
+   */
+  servers: AiMcpServer[];
+  /** merged-tool-key -> provenance (#489), for the per-run recovery wrapper. */
+  toolMeta: Record<string, ToolProvenance>;
   expiresAt: number;
   /** Active leases (turns currently using these clients). */
   refCount: number;
@@ -120,20 +181,82 @@ export class McpClientsService {
    */
   private readonly cache = new Map<string, Promise<CacheEntry>>();
   /**
-   * A single shared SSRF-pinned dispatcher for ALL outbound external-MCP fetches.
-   * Its custom connect.lookup runs per connection, so one instance safely guards
-   * every server's connections (we never connect to an unvalidated IP).
+   * SSRF-pinned dispatchers for outbound external-MCP fetches. Both use the SAME
+   * custom connect.lookup (so every connection is IP-validated), but carry a
+   * DIFFERENT `bodyTimeout` (#489): the HTTP (streamable) transport opens a fresh
+   * request per call, so it keeps the tight silence timeout; the SSE transport
+   * holds ONE long-lived body open across many calls, so a >1-min idle BETWEEN
+   * calls is LEGITIMATE and must not break the socket — it gets a much larger
+   * bodyTimeout. (headersTimeout stays tight on both.)
    */
-  private readonly dispatcher: Dispatcher = buildPinnedDispatcher();
-  /** guardedFetch bound to the pinned dispatcher; reused by every transport. */
-  private readonly guardedFetch: typeof fetch = (input, init) =>
-    guardedFetch(this.dispatcher, input, init);
+  private readonly dispatcherHttp: Dispatcher = buildPinnedDispatcher(
+    mcpStreamTimeoutMs(),
+  );
+  private readonly dispatcherSse: Dispatcher = buildPinnedDispatcher(
+    mcpSseBodyTimeoutMs(),
+  );
+  /** guardedFetch bound to each dispatcher; picked by transport type in connect(). */
+  private readonly guardedFetchHttp: typeof fetch = (input, init) =>
+    guardedFetch(this.dispatcherHttp, input, init);
+  private readonly guardedFetchSse: typeof fetch = (input, init) =>
+    guardedFetch(this.dispatcherSse, input, init);
+
+  /**
+   * Memoized write-class map (#489), loaded lazily from @docmost/mcp via the
+   * dynamic-import trick. Keyed by tool name (=== mcpName). A tool NOT in the map
+   * (any third-party external MCP tool) classifies as `undefined` -> treated as a
+   * write by the retry gate (the safe default: never blind-retry an unknown tool).
+   * On any load failure the map is `{}` (every tool -> no auto-retry), so a
+   * missing/older @docmost/mcp build only DISABLES retries, never mis-retries.
+   */
+  private writeClassMapPromise: Promise<Record<string, ToolWriteClass>> | null =
+    null;
 
   constructor(
     private readonly repo: AiMcpServerRepo,
     private readonly secretBox: SecretBoxService,
   ) {}
 
+  /**
+   * Whether an external MCP server is the TRUSTED internal Docmost MCP server —
+   * the only server whose tools may be classified by the Docmost write-class map
+   * (#489 review). Today this is ALWAYS false: every `ai_mcp_servers` row is an
+   * admin-configured THIRD-PARTY endpoint (there is no builtin/self flag, sentinel
+   * URL, or synthetic server in this path — Docmost's OWN tools are exposed via the
+   * separate in-app tools path, never through this external-MCP client). So no
+   * third-party tool can inherit `readOnly` by a name collision with a Docmost read
+   * tool, and none is ever auto-retried on a transport error (which would risk a
+   * double-apply — the #435 class). Flip this (an explicit `kind`/`isBuiltin`
+   * column, or a configured self-MCP URL) if a trusted internal server is ever
+   * introduced. A method (not a free function) so it is a single, mockable seam.
+   */
+  private isInternalDocmostServer(_server: AiMcpServer): boolean {
+    return false;
+  }
+
+  /** Lazily load + memoize the shared write-class map (see the field doc). */
+  private getWriteClassMap(): Promise<Record<string, ToolWriteClass>> {
+    if (!this.writeClassMapPromise) {
+      this.writeClassMapPromise = (async () => {
+        try {
+          const entry = require.resolve('@docmost/mcp');
+          const mod = (await esmImport(pathToFileURL(entry).href)) as {
+            SHARED_TOOL_WRITE_CLASS?: Record<string, ToolWriteClass>;
+          };
+          return mod.SHARED_TOOL_WRITE_CLASS ?? {};
+        } catch (err) {
+          this.logger.warn(
+            `Could not load MCP write-class map (auto-retry disabled): ${shortError(
+              err,
+            )}`,
+          );
+          return {};
+        }
+      })();
+    }
+    return this.writeClassMapPromise;
+  }
+
   /**
    * Build (or reuse a cached) external toolset for a workspace. Returns the
    * merged tools, the open client handles to release, and per-server outcomes.
@@ -162,11 +285,37 @@ export class McpClientsService {
         }
       },
     };
-    // One release handle drives the whole leased entry; closing it releases all
-    // underlying clients together (they share the same lease lifecycle).
+
+    // #489: the run accumulates a SET of leases — the primary cache lease PLUS any
+    // throwaway client minted by an in-run transport-recovery reconnect. They are
+    // NEVER released mid-run (releasing a swapped-out client while a concurrent
+    // in-flight call still holds it would INDUCE a second failure); the caller
+    // releases the WHOLE set together at turn-end. A recovery reconnect pushes its
+    // lease onto this live array, which the consumer closes over.
+    const leaseSet: Closable[] = [release];
+
+    // #489: per-RUN transport-recovery binding, one per server, SHARED by all of
+    // that server's tools so a swap by one call is seen by the next (CAS by
+    // identity). Kept per-run (here, not in the cached entry) because the binding
+    // + lease-set state is per-run.
+    const bindings = new Map<number, ServerBinding>();
+    const capMs = mcpCallTimeoutMs();
+
+    // Wrap each cached tool with the recovery layer. On a transport error a
+    // declared readOnly tool reconnects its server and retries ONCE; a write is
+    // never blind-retried (indeterminate — may have applied before the reset). A
+    // tool without provenance (a minimal stub entry in a test) passes through raw.
+    const tools: Record<string, Tool> = {};
+    for (const [key, tool] of Object.entries(entry.tools)) {
+      const meta = entry.toolMeta?.[key];
+      tools[key] = meta
+        ? this.wrapWithTransportRecovery(entry, meta, tool, leaseSet, bindings, capMs)
+        : tool;
+    }
+
     return {
-      tools: entry.tools,
-      clients: [release],
+      tools,
+      clients: leaseSet,
       outcomes: entry.outcomes,
       instructions: entry.instructions,
     };
@@ -254,6 +403,16 @@ export class McpClientsService {
     // Per-call total wall-clock cap, read once for this build (env-overridable).
     const callTimeoutMs = mcpCallTimeoutMs();
     const instructions: McpServerInstruction[] = [];
+    // merged-key -> provenance for the per-run recovery wrapper (#489).
+    const toolMeta: Record<string, ToolProvenance> = {};
+    // Shared Docmost write-class map (#489) — classifies a tool by its raw name.
+    // Loaded ONLY when at least one server is a TRUSTED internal Docmost server
+    // (see isInternalDocmostServer): for third-party servers the map is never
+    // applied (a name collision must not grant readOnly-retry), so we skip the
+    // dynamic ESM load entirely in that (currently universal) case.
+    const writeClassMap = servers.some((s) => this.isInternalDocmostServer(s))
+      ? await this.getWriteClassMap()
+      : null;
 
     // Per-server connect+tools result, still tagged with its server so the merge
     // below can be applied in the SAME order as `servers` (see the parallel note).
@@ -285,9 +444,13 @@ export class McpClientsService {
       try {
         client = await this.connectWithTimeout(server, CONNECT_TIMEOUT_MS);
         const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
+        // Allowlist semantics (#476): null/absent = no restriction (all tools);
+        // ANY array — including `[]` — is authoritative, so an EMPTY allowlist
+        // yields ZERO tools (deny-all). Do NOT add a `.length > 0` escape here:
+        // that read `[]` as falsy and silently widened deny-all to allow-all
+        // (the repo also fails corrupt rows closed to `[]` for the same reason).
         const allow = server.toolAllowlist;
-        const picked =
-          Array.isArray(allow) && allow.length > 0 ? pick(raw, allow) : raw;
+        const picked = Array.isArray(allow) ? pick(raw, allow) : raw;
         // Bound each tool's execute with a per-call total-timeout guard before
         // merging, so a single chatty-but-stuck call is aborted after the cap.
         const guarded = wrapToolsWithCallTimeout(picked, callTimeoutMs);
@@ -327,11 +490,23 @@ export class McpClientsService {
       // against names already merged from earlier servers, so no external
       // tool is silently overwritten on collision. The returned count drives
       // whether this server's prompt guidance is included (≥1 tool merged).
+      // #489 (review): the Docmost write-class map keys by DOCMOST tool names and
+      // may ONLY be trusted for a server KNOWN to be the internal Docmost MCP
+      // server. Every row here is an admin-configured THIRD-PARTY endpoint, so a
+      // third-party WRITE tool that happens to be named like a Docmost read
+      // (getPage, listPages, ...) must NOT inherit readOnly — that would auto-retry
+      // a mutation on a transport error (double-apply, the #435 class). Gate the
+      // map on the trust check; untrusted servers get writeClass=undefined -> the
+      // recovery wrapper treats them as writes and never auto-retries.
+      const trustWriteClass = this.isInternalDocmostServer(server);
       const merged = this.mergeNamespaced(
         tools,
         result.guarded,
         server.name,
         server.id,
+        toolMeta,
+        i,
+        trustWriteClass ? writeClassMap : null,
       );
       outcomes.push({ name: server.name, ok: true });
       // Include this server's guidance ONLY when it actually contributed at
@@ -353,6 +528,8 @@ export class McpClientsService {
       clients,
       outcomes,
       instructions,
+      servers,
+      toolMeta,
       expiresAt: Date.now() + CACHE_TTL_MS,
       refCount: 0,
       evicted: false,
@@ -379,18 +556,33 @@ export class McpClientsService {
     picked: Record<string, Tool>,
     serverName: string,
     serverId: string,
+    toolMeta: Record<string, ToolProvenance>,
+    serverIndex: number,
+    // The Docmost write-class map, or `null` for an UNTRUSTED (third-party)
+    // server whose tools must all default to write (never auto-retried).
+    writeClassMap: Record<string, ToolWriteClass> | null,
   ): { count: number; prefix: string } {
     let count = 0;
-    for (const [name, tool] of Object.entries(namespace(picked, serverName))) {
-      let key = name;
+    for (const { full, raw, tool } of namespace(picked, serverName)) {
+      let key = full;
       if (key in target) {
         const original = key;
-        key = disambiguate(name, serverId, (candidate) => candidate in target);
+        key = disambiguate(full, serverId, (candidate) => candidate in target);
         this.logger.debug(
           `External MCP tool name "${original}" collided; renamed to "${key}"`,
         );
       }
       target[key] = tool;
+      // Record provenance so the per-run recovery wrapper (#489) can reconnect
+      // this tool's server and re-resolve it by its raw name. writeClass is set
+      // ONLY from a TRUSTED (internal-Docmost) map; for a third-party server the
+      // map is null -> writeClass stays undefined -> the wrapper treats the tool
+      // as a write and never auto-retries it (no double-apply on name collision).
+      toolMeta[key] = {
+        serverIndex,
+        rawName: raw,
+        writeClass: writeClassMap ? writeClassMap[raw] : undefined,
+      };
       count += 1;
     }
     return { count, prefix: namespacePrefix(serverName) };
@@ -424,7 +616,10 @@ export class McpClientsService {
         // Defense in depth: re-validate the actual request host on EVERY fetch
         // AND pin the socket to a validated IP via the dispatcher's connect
         // lookup, closing the DNS-rebinding TOCTOU between check and connect.
-        fetch: this.guardedFetch,
+        // #489: the SSE transport uses the raised-bodyTimeout dispatcher (idle
+        // between calls is legit); HTTP uses the tight one.
+        fetch:
+          transportType === 'sse' ? this.guardedFetchSse : this.guardedFetchHttp,
       },
     })) as unknown as McpClient;
     return client;
@@ -505,6 +700,176 @@ export class McpClientsService {
     }
   }
 
+  /**
+   * Wrap one merged external tool with the per-run transport-recovery layer (#489).
+   *
+   * attempt 1 runs on the server's CURRENT binding (the cached client, or a client
+   * a sibling tool already reconnected this run). On a REAL transport error
+   * (undici/@ai-sdk socket/body-timeout shapes — {@link isRetryableConnectError},
+   * NOT a mock) and ONLY for a declared readOnly tool, it reconnects the server
+   * and retries EXACTLY ONCE on the fresh client; a write is surfaced as an
+   * indeterminate error (it may have applied before the reset — never
+   * blind-retried). A single per-call cap bounds BOTH attempts + the reconnect,
+   * and the run's abort signal is checked before the retry AND before minting a
+   * fresh connection (no connection is opened for a stopped run).
+   */
+  private wrapWithTransportRecovery(
+    entry: CacheEntry,
+    meta: ToolProvenance,
+    template: Tool,
+    leaseSet: Closable[],
+    bindings: Map<number, ServerBinding>,
+    capMs: number,
+  ): Tool {
+    const original = template.execute;
+    if (typeof original !== 'function') return template;
+    const service = this;
+    const { serverIndex, rawName, writeClass } = meta;
+
+    let binding = bindings.get(serverIndex);
+    if (!binding) {
+      binding = { current: null };
+      bindings.set(serverIndex, binding);
+    }
+    const boundBinding = binding;
+
+    const execute = async (args: unknown, options: ToolCallOptions) => {
+      // The per-call cap governs the WHOLE sequence (attempt1 + reconnect +
+      // attempt2). Compose it with the run's abort signal so a Stop or the cap
+      // ends any awaited call — @ai-sdk/mcp does not settle on abort, so we RACE.
+      const capController = new AbortController();
+      const capTimer = setTimeout(() => {
+        capController.abort(new Error(`MCP tool call timed out after ${capMs}ms`));
+      }, capMs);
+      capTimer.unref?.();
+      const runSignal = options?.abortSignal;
+      const composed = runSignal
+        ? AbortSignal.any([runSignal, capController.signal])
+        : capController.signal;
+      const stopped = () => runSignal?.aborted === true || capController.signal.aborted;
+
+      const callOn = async (
+        exec: NonNullable<Tool['execute']>,
+      ): Promise<unknown> => {
+        const aborted = new Promise<never>((_, reject) => {
+          const fail = () => reject(abortReason(composed));
+          if (composed.aborted) fail();
+          else composed.addEventListener('abort', fail, { once: true });
+        });
+        return Promise.race([exec(args, { ...options, abortSignal: composed }), aborted]);
+      };
+
+      const execFor = (
+        state: RecoveredServerState | null,
+      ): NonNullable<Tool['execute']> | undefined =>
+        state ? (state.tools[rawName]?.execute as NonNullable<Tool['execute']>) : original;
+
+      try {
+        // Snapshot the target BEFORE the call so a swap by a concurrent call is
+        // detected by identity in the catch.
+        const attemptState = boundBinding.current;
+        const attemptExec = execFor(attemptState);
+        if (typeof attemptExec !== 'function') {
+          throw new Error(`external MCP tool "${rawName}" is not callable`);
+        }
+        try {
+          return await callOn(attemptExec);
+        } catch (err) {
+          // Never retry on a Stop or an exhausted cap.
+          if (stopped()) throw err;
+          // Only a genuine transport break is a recovery candidate.
+          if (!isRetryableConnectError(err)) throw err;
+          // A write tool is INDETERMINATE on a transport error (may have applied
+          // before the reset) — surface that; do NOT auto-retry (double-apply is
+          // the #435 incident class).
+          if (!isReadOnlyWriteClass(writeClass)) {
+            throw new Error(
+              `external MCP tool "${rawName}" hit a transport error and MAY have already ` +
+                `applied on the server — not retried automatically; verify state before ` +
+                `retrying. (${shortError(err)})`,
+            );
+          }
+          // Abort check BEFORE minting a fresh connection (no socket for a
+          // stopped run). LIMITATION (#489, LOW): the reconnect's own connect is
+          // bounded by CONNECT_TIMEOUT_MS but does NOT itself observe `composed`,
+          // so a Stop that lands DURING the handshake is only honored at the next
+          // `stopped()` gate (before the retry) — a bounded ≤5s late-abort window;
+          // the throwaway client is closed at turn-end regardless. Threading
+          // `composed` into the SHARED (CAS-deduped) reconnect is deliberately
+          // avoided: it would let the first caller's abort tear down a reconnect a
+          // concurrent still-live caller depends on.
+          if (stopped()) throw err;
+          // CAS-swap by IDENTITY: mint+swap only if nobody swapped since this
+          // call's snapshot; a losing concurrent call awaits the same reconnect
+          // and retries on the SAME fresh client.
+          let target: RecoveredServerState;
+          if (boundBinding.current === attemptState) {
+            if (!boundBinding.reconnecting) {
+              boundBinding.reconnecting = (async () => {
+                const server = entry.servers[serverIndex];
+                const fresh = await service.reconnectServer(server, capMs);
+                leaseSet.push(fresh.lease); // accumulate; released at turn-end
+                boundBinding.current = fresh.state;
+                return fresh.state;
+              })();
+              // Clear the in-flight marker once it settles (success or failure) so
+              // a LATER death of the new client can reconnect again.
+              void boundBinding.reconnecting.then(
+                () => (boundBinding.reconnecting = undefined),
+                () => (boundBinding.reconnecting = undefined),
+              );
+            }
+            target = await boundBinding.reconnecting;
+          } else {
+            target = boundBinding.current as RecoveredServerState;
+          }
+          // Abort check BEFORE the retry.
+          if (stopped()) throw err;
+          const retryExec = execFor(target);
+          if (typeof retryExec !== 'function') throw err;
+          return await callOn(retryExec);
+        }
+      } finally {
+        clearTimeout(capTimer);
+      }
+    };
+    return { ...template, execute } as unknown as Tool;
+  }
+
+  /**
+   * Reconnect ONE server for an in-run recovery (#489): open a fresh client and
+   * list+wrap its tools. The throwaway client is NOT cached — it is owned by the
+   * RUN via the returned lease (closed at turn-end), independent of the shared
+   * cache entry (whose TTL rebuild heals future turns). On a failure the fresh
+   * client is closed so its socket never leaks.
+   */
+  private async reconnectServer(
+    server: AiMcpServer,
+    capMs: number,
+  ): Promise<{ state: RecoveredServerState; lease: Closable }> {
+    const client = await this.connectWithTimeout(server, CONNECT_TIMEOUT_MS);
+    let tools: Record<string, Tool>;
+    try {
+      const raw = await withTimeout(client.tools(), CONNECT_TIMEOUT_MS);
+      const allow = server.toolAllowlist;
+      const picked =
+        Array.isArray(allow) && allow.length > 0 ? pick(raw, allow) : raw;
+      tools = wrapToolsWithCallTimeout(picked, capMs);
+    } catch (err) {
+      void client.close().catch(() => undefined);
+      throw err;
+    }
+    let released = false;
+    const lease: Closable = {
+      close: async () => {
+        if (released) return;
+        released = true;
+        await client.close().catch(() => undefined);
+      },
+    };
+    return { state: { client, tools }, lease };
+  }
+
   /** Mark an entry evicted; close its clients now if nothing is leasing them. */
   private evict(entry: CacheEntry): void {
     clearTimeout(entry.timer);
@@ -554,22 +919,21 @@ export function validateResolvedAddresses(addrs: readonly LookupAddress[]): {
  * certificate validation still uses the real hostname (we never rewrite the URL
  * to an IP literal).
  */
-function buildPinnedDispatcher(): Agent {
-  // External-MCP traffic uses a DEDICATED, shorter silence timeout
+function buildPinnedDispatcher(bodyTimeoutMs: number): Agent {
+  // External-MCP traffic uses a DEDICATED, shorter HEADERS silence timeout
   // (`AI_MCP_STREAM_TIMEOUT_MS`, default 1 min) — deliberately tighter than the
   // chat provider's 15-min `streamTimeoutMs()` — so a byte-silent/hung MCP
   // upstream is broken in ~1 min instead of 15. We keep the keep-alive options
-  // from `streamingDispatcherOptions()` but OVERRIDE headers/body timeouts.
-  // Accepted trade-off: a legitimately long but byte-silent single tool call,
-  // and an SSE transport idling >1 min BETWEEN tool calls, are also cut here; the
-  // per-call total cap (wrapToolsWithCallTimeout, `AI_MCP_CALL_TIMEOUT_MS`) is the
-  // complementary guard for chatty-but-stuck calls that keep the socket warm yet
-  // never return.
-  const mcpSilenceMs = mcpStreamTimeoutMs();
+  // from `streamingDispatcherOptions()` but OVERRIDE the timeouts. `bodyTimeout`
+  // is passed in per-transport (#489): tight for HTTP (fresh request per call),
+  // raised for SSE (one long-lived body across calls — idle BETWEEN calls is
+  // legit). The per-call total cap (`AI_MCP_CALL_TIMEOUT_MS`) is the complementary
+  // guard for chatty-but-stuck calls that keep the socket warm yet never return.
+  const headersMs = mcpStreamTimeoutMs();
   return new Agent({
     ...streamingDispatcherOptions(),
-    headersTimeout: mcpSilenceMs,
-    bodyTimeout: mcpSilenceMs,
+    headersTimeout: headersMs,
+    bodyTimeout: bodyTimeoutMs,
     connect: {
       lookup: (hostname, _options, callback) => {
         // Always resolve ALL addresses ourselves; do not trust the caller's
@@ -669,18 +1033,22 @@ function pick(
 function namespace(
   tools: Record<string, Tool>,
   serverName: string,
-): Record<string, Tool> {
+): Array<{ full: string; raw: string; tool: Tool }> {
   const prefix = namespacePrefix(serverName);
-  const out: Record<string, Tool> = {};
+  const out: Array<{ full: string; raw: string; tool: Tool }> = [];
+  const taken: Record<string, true> = {};
   for (const [name, t] of Object.entries(tools)) {
     const safe = sanitizeName(name);
     let full = capName(`${prefix}_${safe}`);
     // Duplicate names within ONE server can still collide after sanitize/
     // truncate — suffix-disambiguate so the second tool is not overwritten.
-    if (full in out) {
-      full = disambiguate(full, '', (candidate) => candidate in out);
+    if (full in taken) {
+      full = disambiguate(full, '', (candidate) => candidate in taken);
     }
-    out[full] = t;
+    taken[full] = true;
+    // Keep the RAW (un-namespaced) name alongside the merged key so the per-run
+    // recovery wrapper (#489) can re-resolve the same tool on a fresh client.
+    out.push({ full, raw: name, tool: t });
   }
   return out;
 }
@@ -804,6 +1172,69 @@ export function wrapToolWithCallTimeout(tool: Tool, ms: number): Tool {
   return { ...tool, execute } as unknown as Tool;
 }
 
+/**
+ * undici / Node network error CODES that mean the connection broke (not an
+ * application-level error) — a transient transport failure a readOnly call may
+ * safely retry after reconnecting. Matched against the REAL error shapes (#489):
+ * a socket reset surfaces as `TypeError: fetch failed` whose `.cause` is an
+ * undici `SocketError { code:'UND_ERR_SOCKET' }`; a body-timeout as
+ * `TypeError: terminated` whose `.cause` is `BodyTimeoutError`. Classifying by
+ * these real codes/names (not by mock errors) is essential — a mock-shaped
+ * predicate would leave eviction silently dead in production while CI is green.
+ */
+const RETRYABLE_TRANSPORT_ERROR_CODES: ReadonlySet<string> = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ECONNABORTED',
+  'EPIPE',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+  'ENETUNREACH',
+  'EHOSTUNREACH',
+  'UND_ERR_SOCKET',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_BODY_TIMEOUT',
+  'UND_ERR_CLOSED',
+  'UND_ERR_DESTROYED',
+]);
+
+/** undici error CLASS names for the same transport-break conditions. */
+const RETRYABLE_TRANSPORT_ERROR_NAMES: ReadonlySet<string> = new Set([
+  'SocketError',
+  'BodyTimeoutError',
+  'HeadersTimeoutError',
+  'ConnectTimeoutError',
+  'ClientClosedError',
+  'ClientDestroyedError',
+]);
+
+/**
+ * Whether `err` is a retryable TRANSPORT break (a broken socket / body timeout),
+ * classified by the REAL undici/@ai-sdk error shapes (#489). undici surfaces a
+ * reset as `TypeError('fetch failed'|'terminated')` with the real error in
+ * `.cause`, and @ai-sdk/mcp may wrap it again in an `MCPClientError` (cause
+ * chain), so we walk `.cause` (bounded depth) checking `.code` and `.name`. An
+ * app-level tool error (a 4xx, a validation failure) is NOT retryable and returns
+ * false — only a connection-level failure heals with a reconnect.
+ */
+export function isRetryableConnectError(err: unknown, depth = 0): boolean {
+  if (!err || typeof err !== 'object' || depth > 6) return false;
+  const e = err as {
+    code?: unknown;
+    name?: unknown;
+    cause?: unknown;
+  };
+  if (typeof e.code === 'string' && RETRYABLE_TRANSPORT_ERROR_CODES.has(e.code)) {
+    return true;
+  }
+  if (typeof e.name === 'string' && RETRYABLE_TRANSPORT_ERROR_NAMES.has(e.name)) {
+    return true;
+  }
+  if (e.cause != null) return isRetryableConnectError(e.cause, depth + 1);
+  return false;
+}
+
 /** The signal's reason as an Error (informative thrown value on abort/timeout). */
 function abortReason(signal: AbortSignal): Error {
   const r = signal.reason;

apps/server/src/core/ai-chat/external-mcp/mcp-servers.service.ts

@@ -100,7 +100,8 @@ export class McpServersService {
       transport: dto.transport,
       url: dto.url,
       headersEnc,
-      // undefined => unchanged; [] / value handled by repo (empty => null).
+      // undefined => unchanged; null => no restriction; `[]` is persisted
+      // verbatim and means deny-all (#476).
       toolAllowlist: dto.toolAllowlist,
       // undefined => unchanged; blank => cleared (null) by the repo.
       instructions: dto.instructions,

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

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

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

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

apps/server/src/core/ai-chat/output-degeneration.spec.ts

@@ -9,9 +9,73 @@ import {
   DEGENERATION_CHECK_STEP,
   REPEATED_LINES_THRESHOLD,
   MIN_PERIOD_REPEATS,
+  degenerationThresholds,
 } from './output-degeneration';
 import { AiChatService } from './ai-chat.service';
 
+// Part A (#495 iter10): the detector thresholds are env-tunable. These drive the
+// resolver against real repeat-count shapes and mutation-verify that the env
+// override actually changes the trigger point (not a vacuous read).
+describe('degeneration thresholds are env-configurable', () => {
+  const VARS = [
+    'AI_CHAT_DEGENERATION_REPEATED_LINES',
+    'AI_CHAT_DEGENERATION_PERIOD_MAX_LEN',
+    'AI_CHAT_DEGENERATION_PERIOD_MIN_REPEATS',
+    'AI_CHAT_DEGENERATION_CHECK_STEP',
+  ];
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const v of VARS) saved[v] = process.env[v];
+  });
+  afterEach(() => {
+    for (const v of VARS) {
+      if (saved[v] === undefined) delete process.env[v];
+      else process.env[v] = saved[v];
+    }
+  });
+
+  it('defaults to the compiled constants when unset', () => {
+    for (const v of VARS) delete process.env[v];
+    expect(degenerationThresholds()).toEqual({
+      repeatedLines: REPEATED_LINES_THRESHOLD,
+      maxPeriodLen: 150,
+      minPeriodRepeats: MIN_PERIOD_REPEATS,
+      checkStep: DEGENERATION_CHECK_STEP,
+    });
+  });
+
+  it('falls back to the default on blank / invalid / non-positive values', () => {
+    for (const bad of ['', '  ', 'abc', '0', '-3', '1.5']) {
+      process.env.AI_CHAT_DEGENERATION_REPEATED_LINES = bad;
+      // '1.5' floors to 1 (still ≥1, valid); every other bad value → default.
+      const expected = bad === '1.5' ? 1 : REPEATED_LINES_THRESHOLD;
+      expect(degenerationThresholds().repeatedLines).toBe(expected);
+    }
+  });
+
+  it('a RAISED check-step suppresses a burst the default would have flagged', () => {
+    // A ~3.3KB periodic burst is periodic-degenerate, but shouldCheckDegeneration
+    // is the throttle gate. Default checkStep=2000 arms on it; raising the step
+    // above the burst size means the throttle never re-fires for it.
+    const burstLen = 'loadTools.\n'.repeat(300).length; // ~3300
+    delete process.env.AI_CHAT_DEGENERATION_CHECK_STEP;
+    expect(shouldCheckDegeneration(burstLen, 0)).toBe(true); // default 2000
+    process.env.AI_CHAT_DEGENERATION_CHECK_STEP = String(burstLen + 1);
+    expect(shouldCheckDegeneration(burstLen, 0)).toBe(false); // raised gate
+  });
+
+  it('a LOWERED repeated-lines threshold trips on a shorter identical-line run', () => {
+    // 8 identical lines: below the default 25 (rule 1) and below the periodic
+    // rule's 20 repeats — so isDegenerateOutput is false by default.
+    const shortRun = 'x\n'.repeat(8);
+    delete process.env.AI_CHAT_DEGENERATION_REPEATED_LINES;
+    expect(isDegenerateOutput(shortRun)).toBe(false);
+    // Lower rule 1 to 5 → the 8-line run now trips.
+    process.env.AI_CHAT_DEGENERATION_REPEATED_LINES = '5';
+    expect(isDegenerateOutput(shortRun)).toBe(true);
+  });
+});
+
 // Mock ONLY streamText so we can capture the onChunk/onStepFinish callbacks the
 // service registers and drive them by hand; every other `ai` export the service
 // uses (convertToModelMessages, stepCountIs, …) stays real.

apps/server/src/core/ai-chat/output-degeneration.ts

@@ -23,6 +23,54 @@ export const MAX_PERIOD_LEN = 150;
 /** Rule 2: minimum number of consecutive block repeats to trigger. */
 export const MIN_PERIOD_REPEATS = 20;
 
+/**
+ * Read a positive-integer threshold from an env var, falling back to `fallback`
+ * on unset/blank/invalid/non-positive. Mirrors the `AI_STREAM_PRE_RESPONSE_RETRIES`
+ * resolver in `ai-streaming-fetch.ts`: read the RAW string first so a blank value
+ * is treated as "unset" (→ fallback) rather than coercing to 0. Thresholds must
+ * stay ≥ 1 — a 0/negative would make the detector fire on any text (or never), so
+ * a bad value degrades to the safe compiled default instead. Env-tunable so an
+ * operator can retune the anti-babble guard (#444) without a redeploy, following
+ * the `AI_CHAT_FINAL_STEP_LOCKDOWN` toggle convention.
+ */
+function envThreshold(name: string, fallback: number): number {
+  const rawStr = process.env[name];
+  if (rawStr === undefined || rawStr.trim() === '') return fallback;
+  const raw = Number(rawStr);
+  return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : fallback;
+}
+
+/**
+ * Resolve the degeneration-detector thresholds from the environment, each
+ * defaulting to the compiled constant above. Read fresh per call (not cached at
+ * import) so a test — or a runtime env change — takes effect deterministically.
+ */
+export function degenerationThresholds(): {
+  repeatedLines: number;
+  maxPeriodLen: number;
+  minPeriodRepeats: number;
+  checkStep: number;
+} {
+  return {
+    repeatedLines: envThreshold(
+      'AI_CHAT_DEGENERATION_REPEATED_LINES',
+      REPEATED_LINES_THRESHOLD,
+    ),
+    maxPeriodLen: envThreshold(
+      'AI_CHAT_DEGENERATION_PERIOD_MAX_LEN',
+      MAX_PERIOD_LEN,
+    ),
+    minPeriodRepeats: envThreshold(
+      'AI_CHAT_DEGENERATION_PERIOD_MIN_REPEATS',
+      MIN_PERIOD_REPEATS,
+    ),
+    checkStep: envThreshold(
+      'AI_CHAT_DEGENERATION_CHECK_STEP',
+      DEGENERATION_CHECK_STEP,
+    ),
+  };
+}
+
 /**
  * Rule 1 — ≥`REPEATED_LINES_THRESHOLD` consecutive IDENTICAL non-empty lines at
  * the tail. Catches the classic newline-delimited loop ("loadTools.\n" ×N).
@@ -128,7 +176,11 @@ export function hasPeriodicTail(
  * Pure — the caller owns the abort side effect.
  */
 export function isDegenerateOutput(text: string): boolean {
-  return hasRepeatedLineRun(text) || hasPeriodicTail(text);
+  const cfg = degenerationThresholds();
+  return (
+    hasRepeatedLineRun(text, cfg.repeatedLines) ||
+    hasPeriodicTail(text, cfg.maxPeriodLen, cfg.minPeriodRepeats)
+  );
 }
 
 /**
@@ -154,7 +206,7 @@ export function shouldCheckDegeneration(
   textLen: number,
   lastCheckLen: number,
 ): boolean {
-  return textLen - lastCheckLen >= DEGENERATION_CHECK_STEP;
+  return textLen - lastCheckLen >= degenerationThresholds().checkStep;
 }
 
 /**

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

@@ -307,6 +307,10 @@ export class PublicShareChatService {
         system,
         messages: modelMessages,
         tools,
+        // Pin the AI SDK per-request retry budget explicitly (matches the SDK
+        // default of 2). Connection arithmetic: (1 + maxRetries) × (1 +
+        // AI_STREAM_PRE_RESPONSE_RETRIES) worst-case connects per turn.
+        maxRetries: 2,
         // Bound the agent loop for anonymous callers.
         stopWhen: stepCountIs(5),
         // Cap per-request output so one anonymous call cannot run up the provider

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

@@ -426,6 +426,7 @@ export class AiChatToolsService {
     const {
       sharedToolSpecs,
       createCommentSignalTracker,
+      createListCommentsProbe,
       searchShapes,
       getGuideSection,
     } = await loadDocmostMcp();
@@ -718,7 +719,11 @@ export class AiChatToolsService {
       if (spec.mcpOnly) continue;
       if (spec.inlineBothHosts) continue;
       const run = spec.inAppExecute ?? spec.execute;
-      if (!run) continue; // defensive: a shared spec always carries one of them.
+      // Guaranteed present by assertEverySpecIsRegisterable() (#494), which runs
+      // at tool-specs module load and throws if a non-inline spec the in-app host
+      // registers carries neither inAppExecute nor execute — so this can no longer
+      // silently drop a mis-declared tool. Kept as a type-narrowing guard.
+      if (!run) continue;
       tools[spec.inAppKey] = sharedTool(
         spec,
         (async (args) =>
@@ -764,35 +769,21 @@ export class AiChatToolsService {
     // wrapper below) so the race governs the whole call. The client carries the
     // per-call composite signal via setToolAbortSignal.
     const capMs = inAppToolCallCapMs();
-    if (!createCommentSignalTracker) {
+    // The signal needs BOTH the tracker factory AND the shared count-source probe
+    // factory (#494). Either being absent (a stale @docmost/mcp build or a mocked
+    // loader) => signal disabled, tool results byte-identical.
+    if (!createCommentSignalTracker || !createListCommentsProbe) {
       return wrapInAppToolsWithCap(tools, client, capMs);
     }
 
+    // Shared probe (#494): the SAME factory the standalone MCP host uses, so the
+    // in-app probe body is no longer a hand-mirror that could drift (counting the
+    // full feed newer than the watermark, labelling a hit with the light page
+    // title). `client` supplies the loopback listComments/getPageRaw reads.
     const tracker = createCommentSignalTracker({
-      probe: async (pageId: string, sinceMs: number) => {
-        const { items } = await client.listComments(pageId, true);
-        const count = (items as Array<{ createdAt?: string }>).filter((c) => {
-          const created = c?.createdAt ? new Date(c.createdAt).getTime() : NaN;
-          return Number.isFinite(created) && created > sinceMs;
-        }).length;
-        let title: string | undefined;
-        if (count > 0) {
-          // Title labels the signal; untrusted, defanged by the shared builder.
-          // Fetched only on a hit so the no-signal path never pays for it. Uses
-          // the LIGHT raw page info (title only) — mirroring the standalone MCP
-          // probe's getPageRaw — instead of the heavy getPage (which also renders
-          // Markdown + subpages) just to read one field.
-          try {
-            const res = (await client.getPageRaw(pageId)) as {
-              title?: string;
-            } | null;
-            title = res?.title ?? undefined;
-          } catch {
-            // Title is optional — omit it when the page can't be fetched.
-          }
-        }
-        return { count, title };
-      },
+      probe: createListCommentsProbe(
+        client as unknown as Parameters<typeof createListCommentsProbe>[0],
+      ),
     });
 
     return wrapInAppToolsWithCap(

apps/server/src/core/ai-chat/tools/comment-signal-inapp.spec.ts

@@ -21,7 +21,10 @@ import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs
 // The REAL shared tracker factory, imported from source (same cross-boundary
 // approach the tool-specs spec uses) so the in-app wiring is exercised against
 // exactly the watermark/debounce/injection-safe logic the package ships.
-import { createCommentSignalTracker } from '../../../../../../packages/mcp/src/comment-signal';
+import {
+  createCommentSignalTracker,
+  createListCommentsProbe,
+} from '../../../../../../packages/mcp/src/comment-signal';
 // The REAL client-side citation extractor: proves that the passive signal does
 // NOT strip a tool's citations (the #417 in-app regression this spec guards).
 import { toolCitations } from '../../../../../../apps/client/src/features/ai-chat/utils/tool-parts';
@@ -284,9 +287,13 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
         return fakeClient as DocmostClientLike;
       } as unknown as loader.DocmostClientCtor,
       sharedToolSpecs: SHARED_TOOL_SPECS as unknown as Record<string, loader.SharedToolSpec>,
-      // Wire the REAL factory so the in-app path is exercised end to end.
+      // Wire the REAL factories so the in-app path is exercised end to end —
+      // including the shared count-source probe (#494) the service now builds the
+      // tracker's `probe` from.
       createCommentSignalTracker:
         createCommentSignalTracker as unknown as loader.CommentSignalTrackerFactory,
+      createListCommentsProbe:
+        createListCommentsProbe as unknown as loader.CreateListCommentsProbeFn,
       // Pure no-network draw.io helpers (#424) — required on the loader return;
       // this comment-signal test doesn't exercise them, so no-op stubs suffice.
       searchShapes: (() => []) as unknown as loader.SearchShapesFn,

apps/server/src/core/ai-chat/tools/docmost-client.loader.ts

@@ -150,6 +150,27 @@ export type CommentSignalTrackerFactory = (options: {
   debounceMs?: number;
 }) => CommentSignalTrackerLike;
 
+/**
+ * Local mirror of `@docmost/mcp`'s `createListCommentsProbe` (#494): the SHARED
+ * count-source probe both hosts use, so the in-app probe body is no longer a
+ * hand-copy of the standalone MCP one. Given a client with the light comment feed
+ * + raw-page-title reads, it returns the tracker's `probe` (count comments newer
+ * than the watermark, label a hit with the page title). Loosely typed at this
+ * cross-package boundary, like the rest of this loader.
+ */
+export type CreateListCommentsProbeFn = (client: {
+  listComments(
+    pageId: string,
+    includeResolved: boolean,
+  ): Promise<{ items: Array<{ createdAt?: string | null }> }>;
+  getPageRaw(
+    pageId: string,
+  ): Promise<{ title?: string | null } | null | undefined>;
+}) => (
+  pageId: string,
+  sinceMs: number,
+) => Promise<CommentSignalProbeResultLike>;
+
 // Pure, no-network draw.io helpers (#424). These are plain functions on the
 // module (NOT DocmostClient methods) — the in-app AI-SDK service calls them
 // directly to wire drawioShapes / drawioGuide, mirroring the MCP server.
@@ -170,6 +191,10 @@ interface DocmostMcpModule {
   // loader in unit tests. The in-app layer treats an absent factory as "signal
   // disabled" — a pure no-op that leaves tool results byte-identical.
   createCommentSignalTracker?: CommentSignalTrackerFactory;
+  // Optional (#494): the shared count-source probe factory. Absent on a pre-#494
+  // build or a mocked loader; the in-app layer only builds a probe when the
+  // signal factory above is also present.
+  createListCommentsProbe?: CreateListCommentsProbeFn;
   // Optional (#447): a deterministic hash of the tool-specs registry content,
   // generated into build/ by the package's build. Absent on a pre-#447 build (or
   // the mocked loader in unit tests) — the stale-check below is a NO-OP when it
@@ -284,6 +309,7 @@ export async function loadDocmostMcp(): Promise<{
   DocmostClient: DocmostClientCtor;
   sharedToolSpecs: Record<string, SharedToolSpec>;
   createCommentSignalTracker?: CommentSignalTrackerFactory;
+  createListCommentsProbe?: CreateListCommentsProbeFn;
   searchShapes: SearchShapesFn;
   getGuideSection: GetGuideSectionFn;
 }> {
@@ -331,6 +357,9 @@ export async function loadDocmostMcp(): Promise<{
     // Optional: forwarded when present so the in-app layer can build the passive
     // comment signal (#417); undefined on a stale build => signal disabled.
     createCommentSignalTracker: mod.createCommentSignalTracker,
+    // Optional (#494): the shared count-source probe factory; undefined on a
+    // stale build => the in-app layer falls back to no signal.
+    createListCommentsProbe: mod.createListCommentsProbe,
     // Pure no-network draw.io helpers (#424); not client methods.
     searchShapes: mod.searchShapes,
     getGuideSection: mod.getGuideSection,

apps/server/src/core/comment/comment.controller.ts

@@ -16,6 +16,7 @@ import { UpdateCommentDto } from './dto/update-comment.dto';
 import { ResolveCommentDto } from './dto/resolve-comment.dto';
 import { ApplySuggestionDto } from './dto/apply-suggestion.dto';
 import { DismissSuggestionDto } from './dto/dismiss-suggestion.dto';
+import { ResyncSuggestionAnchorDto } from './dto/resync-suggestion-anchor.dto';
 import { PageIdDto, CommentIdDto } from './dto/comments.input';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
 import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
@@ -235,6 +236,39 @@ export class CommentController {
     return this.commentService.applySuggestion(comment, user, provenance);
   }
 
+  @HttpCode(HttpStatus.OK)
+  @Post('resync-suggestion-anchor')
+  async resyncSuggestionAnchor(
+    @Body() dto: ResyncSuggestionAnchorDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    const comment = await this.commentRepo.findById(dto.commentId, {
+      includeCreator: true,
+      includeResolvedBy: true,
+    });
+    if (!comment) {
+      throw new NotFoundException('Comment not found');
+    }
+
+    const page = await this.pageRepo.findById(comment.pageId);
+    if (!page || page.deletedAt) {
+      throw new NotFoundException('Page not found');
+    }
+
+    // Authorize BEFORE revealing structural detail (mirrors apply/dismiss).
+    // Re-anchoring does NOT change the page text — it only corrects the stored
+    // selection metadata — so the page-level gate is comment access. The service
+    // further restricts it to the suggestion's own author.
+    await this.pageAccessService.validateCanComment(page, user, workspace.id);
+
+    return this.commentService.resyncSuggestionAnchor(
+      comment,
+      dto.selection,
+      user,
+    );
+  }
+
   @HttpCode(HttpStatus.OK)
   @Post('dismiss-suggestion')
   async dismissSuggestion(

apps/server/src/core/comment/comment.service.apply-suggestion.spec.ts

@@ -146,11 +146,19 @@ describe('CommentService — applySuggestion', () => {
       'page-1',
       expect.objectContaining({ operation: 'commentDeleted', commentId: 'c-1' }),
     );
+    // #496: hard-deleted row → the audit payload is the only surviving record.
     expect(auditService.log).toHaveBeenCalledWith(
       expect.objectContaining({
         event: AuditEvent.COMMENT_SUGGESTION_APPLIED,
         resourceType: AuditResource.COMMENT,
         resourceId: 'c-1',
+        metadata: expect.objectContaining({
+          pageId: 'page-1',
+          suggestedText: 'new text',
+          selection: 'old text',
+          commentAuthor: 'user-1',
+          decidedBy: 'user-1',
+        }),
       }),
     );
     expect(result.outcome).toBe('deleted');
@@ -189,17 +197,25 @@ describe('CommentService — applySuggestion', () => {
     expect(resolvePatch.resolvedAt).toBeInstanceOf(Date);
     expect(resolvePatch.resolvedById).toBe('user-1');
 
-    // NOT deleted; broadcast an update, not a deletion.
+    // NOT deleted.
     expect(commentRepo.deleteComment).not.toHaveBeenCalled();
     expect(collaborationGateway.handleYjsEvent).not.toHaveBeenCalledWith(
       'deleteCommentMark',
       expect.anything(),
       expect.anything(),
     );
+    // #496 dedup: resolveComment broadcasts `commentResolved` with the enriched
+    // row; finalize must NOT ALSO emit a redundant `commentUpdated`. So the
+    // thread receives exactly ONE resolve broadcast and no update broadcast.
     expect(wsService.emitCommentEvent).toHaveBeenCalledWith(
       'space-1',
       'page-1',
-      expect.objectContaining({ operation: 'commentUpdated', comment: UPDATED }),
+      expect.objectContaining({ operation: 'commentResolved', comment: UPDATED }),
+    );
+    expect(wsService.emitCommentEvent).not.toHaveBeenCalledWith(
+      'space-1',
+      'page-1',
+      expect.objectContaining({ operation: 'commentUpdated' }),
     );
 
     expect(auditService.log).toHaveBeenCalledWith(
@@ -211,6 +227,36 @@ describe('CommentService — applySuggestion', () => {
     expect(result.outcome).toBe('resolved');
   });
 
+  it('re-entry: already applied+resolved WITH replies → emits commentUpdated (dedup does not over-suppress)', async () => {
+    // suggestionAppliedAt set → idempotent finalize; resolvedAt set → resolveComment
+    // is skipped, so there is NO commentResolved broadcast. The applied-stamp state
+    // must still reach clients via a single commentUpdated.
+    const { service, wsService } = makeService(
+      { applied: false, currentText: 'new text' },
+      true,
+    );
+
+    await service.applySuggestion(
+      suggestionComment({
+        suggestionAppliedAt: new Date(),
+        resolvedAt: new Date(),
+      }),
+      user(),
+    );
+
+    expect(wsService.emitCommentEvent).toHaveBeenCalledWith(
+      'space-1',
+      'page-1',
+      expect.objectContaining({ operation: 'commentUpdated', comment: UPDATED }),
+    );
+    // Nothing resolved this time (already resolved) → no resolve broadcast.
+    expect(wsService.emitCommentEvent).not.toHaveBeenCalledWith(
+      'space-1',
+      'page-1',
+      expect.objectContaining({ operation: 'commentResolved' }),
+    );
+  });
+
   // --- error / rejection branches -----------------------------------------
 
   it('applied=false and currentText differs → ConflictException with currentText in payload', async () => {