fix(#486): ревью — CHANGELOG + AGENTS.md + два теста

Ре-ревью PR #500 (changes-requested, 4 мелких, все doc/test):

F1 [CHANGELOG] CHANGELOG.md [Unreleased]:
- Breaking Changes: metrics-листенер 0.0.0.0→127.0.0.1 — кросс-контейнерный
  скрейп (docmost:9464) молча умрёт без METRICS_BIND=0.0.0.0 + METRICS_TOKEN
  (миграция в .env.example).
- Security: утечка errorText тулов/провайдера анониму (closes #394);
  /metrics под Bearer (METRICS_TOKEN).
- Fixed: ioredis-утечка в /health; ELK вешал event loop; beginRun-призрак →
  честный 503 A_RUN_BEGIN_FAILED; ai drain-hang.

F2 [AGENTS.md] строка про ai-патч: теперь он несёт ДВА фикса (#184 O(n²)
partialOutput И #486 drain-hang), оба тривайра названы.

F3 [test] metrics.server.spec: добавлен кейс токена ТОЙ ЖЕ длины
(Bearer topsecreX) → 401 — пиннит constant-time сравнение (прежние кейсы
коротили на length-guard, до timingSafeEqual не доходили).

F4 [test] output-degeneration.spec: behavior-тест, гоняющий РЕАЛЬНЫЕ
onChunk/onStepFinish из stream() — длинный чистый шаг → граница → свежий
дегенеративный бёрст → ассерт abortSignal.aborted (было хардкодом
resetWatermark=0, ревёрт правки не краснил).

Мутационные пруфы (non-vacuous): F3 — форс compare→true роняет same-length
кейс (401→200); F4 — ревёрт lastDegenerationCheckLen=0 роняет behavior-тест
(aborted true→false). Оба восстановлены, специи зелёные (34/34).

.env.example

@@ -124,6 +124,40 @@ MCP_DOCMOST_PASSWORD=
 # MCP_TOKEN=
 # MCP_SESSION_IDLE_MS=1800000
 #
+# --- MCP collaboration write path: concurrency + rights-staleness (#449) ------
+# MCP content writes (update_page, insert/replace nodes, comments-in-body, etc.)
+# go over the collaboration websocket and are serialized PER PAGE by an
+# in-process mutex (a module-level Map, one promise-chain per page UUID). This
+# guarantees no two MCP writes on the SAME page overlap and clobber each other.
+#
+# DEPLOY REQUIREMENT — SINGLE INSTANCE or STICKY SESSIONS. The mutex is
+# process-local. Behind a multi-replica load balancer WITHOUT sticky sessions,
+# two replicas can each "hold" the lock for the same page at the same time and
+# serialization is silently lost (concurrent full-document writes race on the
+# live Yjs fragment). Run the MCP/app as a SINGLE instance, OR pin a page's
+# traffic to one replica (sticky sessions / consistent hashing on page id). The
+# same constraint applies to the RAM-only stash_page blob store above. There is
+# deliberately no cross-process (e.g. Postgres advisory) lock yet — this is a
+# CONSCIOUS documented constraint, not an oversight (#449).
+#
+# To reduce connect-storms the write path caches ONE live collab session per
+# (wsUrl, page, token). Tunables (all optional; defaults are safe):
+# MCP_COLLAB_SESSION_IDLE_MS=60000     # idle TTL, reset per op; 0 disables cache
+# MCP_COLLAB_SESSION_MAX_ENTRIES=32    # LRU cap on cached sessions
+# MCP_COLLAB_TOKEN_TTL_MS=300000       # per-client collab-token cache (5 min)
+#
+# RIGHTS-STALENESS TRADE-OFF. A cached collab session writes under the token
+# captured at CONNECT time, and the collab-token cache reuses a token for its TTL.
+# So if a user's access to a page is REVOKED, MCP writes on an already-open
+# session may keep succeeding until the session ages out. MCP_COLLAB_SESSION_MAX_AGE_MS
+# is the HARD lifetime (checked at each acquire) that BOUNDS this window: after it,
+# the session is torn down and the next write re-auths with a fresh token, picking
+# up the revocation. Default 10 min. LOWER it to shorten the revocation lag at the
+# cost of more reconnects; RAISE it to reduce reconnects at the cost of a longer
+# stale-rights window. There is intentionally no push-based cache invalidation on
+# a rights change — this bounded window is the accepted trade-off (#449).
+# MCP_COLLAB_SESSION_MAX_AGE_MS=600000
+#
 # BLOB SANDBOX (stash_page). An in-RAM, process-local store that hands large page
 # content + images to an external consumer WITHOUT bloating the model context or
 # requiring Docmost auth. The stash_page tool serializes a page, mirrors its
@@ -217,6 +251,17 @@ MCP_DOCMOST_PASSWORD=
 # active" behavior.
 # AI_CHAT_DEFERRED_TOOLS=true
 
+# Final-step lockdown for the in-app agent loop (#444). Default OFF. When ON
+# (legacy), the LAST allowed step forces a text-only answer: the model's tools are
+# stripped (toolChoice=none) and a synthesis instruction is appended. That
+# tool-stripping caused a token-degeneration incident — robbed of its tools on the
+# final step mid-work, the model emitted a ~255KB block repeating a single token —
+# so the default is now OFF: the last step keeps its tools and gets only a SOFT
+# nudge to finish with a text summary, and a token-degeneration detector is the
+# universal anti-babble guard. Enable this ONLY for a model that reliably ends its
+# turns with a clear text answer.
+# AI_CHAT_FINAL_STEP_LOCKDOWN=false
+
 # --- Autonomous / detached agent runs (settings.ai.autonomousRuns) ---
 # Opt-in per workspace (AI settings; off by default). When on, a chat turn becomes
 # a server-side RUN that survives a browser disconnect — only an explicit Stop ends
@@ -290,6 +335,20 @@ MCP_DOCMOST_PASSWORD=
 #    VictoriaMetrics/Prometheus reaching it as <host>:<port>/metrics.
 # METRICS_PORT=9464
 #
+#    METRICS_BIND — interface the /metrics listener binds to. DEFAULT 127.0.0.1
+#    (loopback only), so the unauthenticated endpoint is NOT exposed on all
+#    interfaces. If the scraper runs in a SEPARATE container and reaches this as
+#    docmost:9464, set METRICS_BIND=0.0.0.0 — but then also set METRICS_TOKEN
+#    and/or keep the port on a private network, since /metrics is otherwise open.
+# METRICS_BIND=127.0.0.1
+#
+#    METRICS_TOKEN — optional Bearer token guarding /metrics. When set, every
+#    scrape MUST send `Authorization: Bearer <token>` (others get 401). Configure
+#    the scraper with the same bearer token (e.g. VictoriaMetrics/vmagent
+#    `bearer_token`, Prometheus `authorization.credentials`). Leave unset only
+#    when the endpoint is bound to loopback or an otherwise-trusted network.
+# METRICS_TOKEN=
+#
 # 2) CLIENT_TELEMETRY_ENABLED — the public client perf-telemetry sink.
 #    OFF by default. When true, the unauthenticated POST /api/telemetry/vitals
 #    endpoint is registered and browsers collect + send web-vitals / editor

.github/workflows/develop.yml

@@ -157,6 +157,12 @@ jobs:
       - name: Build prosemirror-markdown
         run: pnpm --filter @docmost/prosemirror-markdown build
 
+      # docmost-client.loader.ts type-imports from @docmost/mcp (issue #446); its
+      # build/ is gitignored and `test:e2e` type-checks, so build it here or tsc
+      # fails with TS2307 (mirrors the e2e-mcp / mcp-server-parity jobs).
+      - name: Build mcp
+        run: pnpm --filter @docmost/mcp build
+
       - name: Run migrations
         run: pnpm --filter ./apps/server migration:latest
 

.github/workflows/test.yml

@@ -1,5 +1,13 @@
 name: Test
 
+# NO `paths:` filter on purpose (issue #447). The tool-spec REGISTRY is split
+# across two packages that MUST stay in sync: the specs live in `packages/mcp`
+# but the parity/tier guard tests that read them live in the `apps/server` jest
+# suite. A PR touching only `packages/mcp/**` must therefore still run the SERVER
+# suite (and vice-versa), or an in-app wiring break slips through green and only
+# surfaces on develop after merge. The `test` job below runs BOTH suites via
+# `pnpm -r test` on every PR; the dedicated `mcp-server-parity` job makes that
+# cross-package gate explicit and fast. Do not add a `paths:` filter here.
 on:
   pull_request:
   workflow_call:
@@ -132,3 +140,53 @@ jobs:
       # isolated `docmost_test` DB and migrates it to latest.
       - name: Run server integration tests
         run: pnpm --filter server test:int
+
+  # Cross-package tool-spec parity gate (issue #447). The tool-spec registry lives
+  # in `packages/mcp` but its parity/tier guard tests live in the `apps/server`
+  # jest suite, so a PR touching ONLY one of the two packages must still run BOTH
+  # sides — otherwise an in-app wiring break (e.g. PR #434 drawio) passes the mcp
+  # suite green and only surfaces on develop after merge. The `test` job already
+  # runs everything via `pnpm -r test`; this job is a fast, explicitly-named guard
+  # that runs the mcp `node --test` suite AND the server tool-guard jest specs
+  # together, so the coupling is visible and can never be accidentally split by a
+  # path filter. No Postgres/Redis needed: these specs mock the DB/loader.
+  mcp-server-parity:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Shared deps first (build/ dirs are gitignored; see test.yml build order).
+      - name: Build editor-ext
+        run: pnpm --filter @docmost/editor-ext build
+
+      - name: Build prosemirror-markdown
+        run: pnpm --filter @docmost/prosemirror-markdown build
+
+      # Build the mcp package so build/ carries a FRESH REGISTRY_STAMP (#447): the
+      # build runs gen-registry-stamp.mjs before tsc, so a build/ vs src/ skew
+      # cannot slip into the tests that exercise the loader's stale-check.
+      - name: Build mcp (regenerates REGISTRY_STAMP)
+        run: pnpm --filter @docmost/mcp build
+
+      # mcp side: the standalone MCP server's own tool-spec / instructions guards.
+      - name: Run mcp tool-spec suite
+        run: pnpm --filter @docmost/mcp test
+
+      # server side: the parity + tier guards that read packages/mcp/src/tool-specs
+      # and assert the in-app AI-chat wiring matches it.
+      - name: Run server tool-spec guard specs
+        run: pnpm --filter server exec jest shared-tool-specs.contract tool-tiers ai-chat-tools.service --runInBand

.gitignore

@@ -2,6 +2,11 @@
 .env.dev
 .env.prod
 data
+# Exception: the committed draw.io shape catalog (issue #424) lives in a `data/`
+# dir, but the bare `data` ignore above is meant for runtime state, not this
+# bundled build asset. Re-include the directory and its contents.
+!packages/mcp/data/
+!packages/mcp/data/**
 # compiled output
 /dist
 node_modules
@@ -19,6 +24,11 @@ packages/prosemirror-markdown/build/
 # markdown convention; the package is private and rebuilt at deploy.
 packages/mcp/build/
 
+# mcp REGISTRY_STAMP codegen output (issue #447). Regenerated into src/ by
+# scripts/gen-registry-stamp.mjs on every `build`/`pretest` (before tsc), so it
+# is a build artifact like build/ — never committed, always fresh.
+packages/mcp/src/registry-stamp.generated.ts
+
 # Logs
 logs
 *.log

AGENTS.md

@@ -5,6 +5,139 @@ repository. It has two layers: **how to run a task end-to-end** (the
 sections below), and **how the codebase is built** (the technical sections
 further down, formerly in `CLAUDE.md`).
 
+## ARCHITECTURAL INVARIANTS — NON-NEGOTIABLE
+
+THE TEN RULES BELOW ARE HARD CONSTRAINTS. Each one was paid for with a real
+production incident or a multi-PR bug chain in THIS repository (cited inline).
+They override convenience, deadlines and "it's just a small feature". A PR that
+violates any of them MUST be rejected in review regardless of how good the rest
+of it is. If a task genuinely seems to require breaking one — STOP and raise it
+with the owner; do not code around it.
+
+### 1. EVERY BUFFER, CACHE, HISTORY AND PAYLOAD HAS AN EXPLICIT SIZE BUDGET
+
+Nothing accumulates unboundedly. A row/item cap is NOT a byte cap. Anything
+replayed to a model, buffered in memory, persisted per step, or refetched by a
+poll must state its budget in bytes/tokens and enforce it. Rewriting a growing
+structure in full on every increment is FORBIDDEN — append or diff instead;
+O(n²) write/serialize patterns do not pass review.
+(Paid for by: full-row rewrite on every agent step — hundreds of MB of Postgres
+writes per 50-step run, with every tool output serialized twice; unbounded
+history replay killing long chats on the provider context window; 32 MB replay
+buffers per active run.)
+
+### 2. EVERYTHING LONG-RUNNING TERMINATES BY CONSTRUCTION
+
+Every run / row / session / lease / subscriber / queue entry must define AT
+DESIGN TIME: its owner; every terminal state; who writes the terminal state on
+EVERY path (success, error, abort, disconnect in each phase, process restart);
+retries for the terminal write; and a periodic sweeper that does not depend on
+a reboot. A best-effort terminal write with no retry and no sweep is FORBIDDEN.
+(Paid for by: assistant rows stuck 'streaming' forever; runs stuck 'running'
+409-locking their chat until a restart — the #183/#184 follow-up chain.)
+
+### 3. EVERY AWAIT IS CANCELLABLE AND DEADLINED; NEVER BLOCK THE EVENT LOOP
+
+Every async step inside a request or agent turn honors the turn's AbortSignal
+AND a wall-clock deadline — including in-app tools, lock queues and pagination
+loops, not just external calls. Synchronous CPU work beyond ~50 ms goes to a
+worker_thread. Promise.race DOES NOT cancel synchronous work — using it as a
+"timeout" for sync computation is forbidden (the timer only fires after the
+event loop is free again, i.e. after the damage is done).
+(Paid for by: in-app tools ignoring abortSignal and writing pages AFTER Stop;
+the synchronous ELK layout freezing every SSE stream in the process; the
+step-0 MCP handshake hang — #397.)
+
+### 4. ONE SOURCE OF TRUTH; EVERYTHING ELSE IS A REBUILDABLE CACHE
+
+Postgres is the authoritative state. Every in-memory structure (registries,
+caches, client stores) must be reconstructible from the DB and treated as
+lossy. The client renders SERVER-DECLARED state — "a run is active" is a server
+fact delivered as data, never inferred from side signals (204 vs 2xx, the
+flavor of a disconnect). A new feature must name the owner of each piece of
+state before implementation starts.
+(Paid for by: the strip/restore resume machinery, silently frozen UIs and
+ghost sends after unmount — the #381→#432→#456 chain.)
+
+### 5. STATE MACHINES ARE EXPLICIT — ONE-SHOT FLAGS ARE FORBIDDEN
+
+A complex lifecycle (chat thread, resume/reconnect, run) lives in a named-state
+automaton (reducer / enum) where every state has an owner and a rendered
+representation — including the failure states. Adding a boolean ref that one
+callback arms and another reads-and-clears is FORBIDDEN in the AI-chat client.
+New behavior = a new named state + explicit transitions, and the interruption
+matrix (disconnect in each phase × restart × stop × supersede) is enumerated at
+design time, not discovered one incident at a time.
+(Paid for by: 26 one-shot useRef flags in chat-thread.tsx and the drip of
+"one more missing transition" across #381→#386/#389→#432→#456.)
+
+### 6. NO NEW MODE FORKS; A FLAG IS FOR ROLLOUT, THEN IT DIES
+
+A behavior flag that forks a code path must ship with a written sunset
+condition; stacking a new flag onto the existing matrix without deleting or
+scheduling an old one is forbidden. While a temporary fork exists, BOTH sides
+must share identical lifecycle handling (abort semantics, error listeners,
+concurrency gates) — asymmetric forks are outlawed.
+(Paid for by: legacy vs autonomous divergence — the one-active-run gate and
+the socket 'error' listener each existing on only ONE side; 2^4 flag
+combinations each with different abort semantics.)
+
+### 7. NO HAND-SYNCED MIRRORS — CODEGEN OR A CI PARITY TEST, NOTHING LESS
+
+Two copies of the same knowledge (schema, tool registry, glyph map, probe
+body, hash/normalize algorithm, label list) require either generation from a
+single source or a CI test that FAILS on drift. A "mirror this change over
+there" comment is NOT a guard and does not pass review.
+(Paid for by: #293 — three drifting converter copies losing data; #447 —
+REGISTRY_STAMP covering only one of the mirrored files; ~10 still-unguarded
+mirrors across the MCP layer.)
+
+### 8. CACHES, HEADERS, BUFFERS AND FSM TRANSITIONS GET AN INTEGRATION TEST OF THE OBSERVABLE PROPERTY
+
+A unit test of a pure helper DOES NOT COUNT for these. Test the real header on
+the real HTTP response, the real cache hit under real token sources, the real
+transition under a really-killed socket. If the observable property cannot be
+tested, the design is wrong — fix the design, not the test.
+(Paid for by: #431→#439 — a cache keyed on a fresh-per-call JWT, so it NEVER
+hit and became prod incident #435 while its unit tests stayed green; and by
+the #352→#455 immutable-cache header silently overwritten by a framework
+default AFTER the unit-tested code ran.)
+
+### 9. CLIENT INPUT IS HOSTILE UNTIL VALIDATED — ALSO BEFORE PERSISTENCE
+
+Anything from the browser (message parts, ids, titles, selections, flags) is
+validated/sanitized BEFORE it is persisted into a row that will later be
+replayed into a prompt, a converter or another subsystem. A poisoned row must
+never be able to permanently brick a chat or a page on every subsequent read.
+(Paid for by: unvalidated UIMessage parts persisted verbatim — one bad row
+500s the chat on every later turn; #159 client-spoofed page titles; #388
+selection re-sanitized server-side for the same reason.)
+
+### 10. FAILURES ARE LOUD AND SPECIFIC; SILENT DEGRADATION IS FORBIDDEN
+
+Extends the error convention below: a fire-and-forget write is allowed ONLY
+with a metric or a greppable ERROR log; a degraded mode (dead cached MCP
+client, stopped poll, exhausted retries, evicted buffer) must be VISIBLE to
+the user or the operator. A feature that can quietly stop working — a frozen
+"streaming…" UI, a poll that silently gives up, a cache serving corpses — does
+not pass review.
+(Paid for by: the degraded poll's silent 10-minute death leaving a forever-
+"streaming" answer; dead MCP clients served from cache while every external
+tool call failed; #435 being caught in minutes ONLY because metrics — #403 —
+existed.)
+
+## Default skill for feature design
+
+For any feature-design request — the user hands over a raw feature idea, asks
+to design or think through a feature, or to draft an issue («спроектируй»,
+«продумай фичу», «составь ишью», "design X", "write an issue for X") — invoke
+the `orchestrator-feature-designer` skill (Skill tool) BEFORE any other work.
+It is the default operating mode for design work in this repository: research
+→ design checklist (R1–R10) → forks resolved with the human → adversarial
+self-attack → filed PR-sized issues. Do not design features or write issues
+ad-hoc while this skill is available. This does not apply to non-design work
+(bug fixes, reviews, retrospectives, refactors already specified by an issue).
+
 ## Task lifecycle
 
 ### 1. Start: sync with develop
@@ -248,6 +381,22 @@ pnpm collab:dev              # run the collaboration server process standalone (
 > that order). Reach for it whenever you run a consumer package's checks on their
 > own rather than through the full `pnpm build`.
 
+> **Editing an MCP tool spec requires a rebuild (issue #447).** The running
+> server loads the **compiled** `packages/mcp/build/` of `@docmost/mcp` (via the
+> runtime loader in `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts`),
+> but the parity/tier guard tests read `packages/mcp/src/tool-specs.ts`. So if you
+> edit `tool-specs.ts` (any tool name, description, tier, catalog line, or input
+> schema) **without rebuilding**, `build/` and `src/` silently diverge — the tests
+> stay green while the server serves the OLD tools. To close that gap, the build
+> emits a `REGISTRY_STAMP` (a deterministic hash of the tool-specs content, via
+> `scripts/gen-registry-stamp.mjs` before `tsc`); on dev/test startup the loader
+> recomputes it from `src/` and **refuses to start with a "@docmost/mcp build is
+> stale …" error** on a mismatch (a pure no-op in prod, where only `build/` ships).
+> After editing tool specs, rebuild:
+> ```bash
+> pnpm --filter @docmost/mcp build     # or: pnpm --filter @docmost/mcp watch
+> ```
+
 **Lint** (per package — there is no root lint script):
 ```bash
 pnpm --filter server lint    # eslint --fix on server .ts
@@ -321,8 +470,8 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - **Errors must never be swallowed or shown as generic messages.** Every caught error MUST (1) be logged in full to the console/logger — error name, message, stack, `cause`, and (for HTTP/provider failures) the status code and response body — and (2) be surfaced to the user with a *specific, human-readable explanation of what actually went wrong*, never a bare generic string like "Something went wrong" / "Could not start recording" / "Transcription failed". Include the real reason (the underlying error/provider message) in the user-facing text. On the server, wrap third-party/provider failures with `describeProviderError` (or equivalent) and rethrow as a meaningful HTTP status + message — never let them collapse into an opaque 500. On the client, `console.error(<context>, err)` the raw error AND show the extracted reason (e.g. `err.response?.data?.message`, or the error `name: message`) in the notification.
 - 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 disables the SDK's O(n²) cumulative `partialOutput` accumulation when no output strategy is requested (server heap OOM on long agent runs, #184; tripwire test: `apps/server/src/integrations/ai/ai-sdk-partial-output.patch.spec.ts`) — it MUST be re-created via `pnpm patch` when bumping `ai`.
-- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). `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.
+- 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`.
+- **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

@@ -10,6 +10,123 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Breaking Changes
+
+- **External MCP tool names are now camelCase (all renamed).** Every tool on the
+  external `/mcp` surface was renamed from `snake_case` to `camelCase`, so the
+  external MCP name now matches the in-app tool name exactly (one logical tool,
+  one name everywhere). For example `get_node` → `getNode`, `edit_page_text` →
+  `editPageText`, `patch_node` → `patchNode`. The tools' behaviour, inputs and
+  outputs are unchanged — only the names change. The single-word `search`
+  keeps its name.
+
+  *Migration (external MCP clients only — the in-app AI agent already used these
+  names and is unaffected):* update anything that refers to a tool by its
+  string name — permission allowlists (`mcp__gitmost-*__get_node` →
+  `mcp__gitmost-*__getNode`), saved prompts/skills, `.mcp.json` tool filters,
+  and metrics dashboards that group by the `tool` label — and roll it out in
+  lockstep with this deploy, because the old snake_case names stop resolving.
+  Released together with the `import_page_markdown`/`update_page_markdown`
+  change below so external configs break exactly once.
+
+  Full mapping (old → new):
+
+  | Old (snake_case) | New (camelCase) |
+  | --- | --- |
+  | `check_new_comments` | `checkNewComments` |
+  | `copy_page_content` | `copyPageContent` |
+  | `create_comment` | `createComment` |
+  | `create_page` | `createPage` |
+  | `delete_comment` | `deleteComment` |
+  | `delete_node` | `deleteNode` |
+  | `delete_page` | `deletePage` |
+  | `diff_page_versions` | `diffPageVersions` |
+  | `docmost_transform` | `docmostTransform` |
+  | `drawio_create` | `drawioCreate` |
+  | `drawio_get` | `drawioGet` |
+  | `drawio_guide` | `drawioGuide` |
+  | `drawio_shapes` | `drawioShapes` |
+  | `drawio_update` | `drawioUpdate` |
+  | `edit_page_text` | `editPageText` |
+  | `export_page_markdown` | `exportPageMarkdown` |
+  | `get_node` | `getNode` |
+  | `get_outline` | `getOutline` |
+  | `get_page` | `getPage` |
+  | `get_page_json` | `getPageJson` |
+  | `get_workspace` | `getWorkspace` |
+  | `insert_footnote` | `insertFootnote` |
+  | `insert_image` | `insertImage` |
+  | `insert_node` | `insertNode` |
+  | `list_comments` | `listComments` |
+  | `list_page_history` | `listPageHistory` |
+  | `list_pages` | `listPages` |
+  | `list_shares` | `listShares` |
+  | `list_spaces` | `listSpaces` |
+  | `move_page` | `movePage` |
+  | `patch_node` | `patchNode` |
+  | `rename_page` | `renamePage` |
+  | `replace_image` | `replaceImage` |
+  | `resolve_comment` | `resolveComment` |
+  | `restore_page_version` | `restorePageVersion` |
+  | `search` | `search` (unchanged) |
+  | `search_in_page` | `searchInPage` |
+  | `share_page` | `sharePage` |
+  | `stash_page` | `stashPage` |
+  | `table_delete_row` | `tableDeleteRow` |
+  | `table_get` | `tableGet` |
+  | `table_insert_row` | `tableInsertRow` |
+  | `table_update_cell` | `tableUpdateCell` |
+  | `unshare_page` | `unsharePage` |
+  | `update_comment` | `updateComment` |
+  | `update_page_json` | `updatePageJson` |
+  | `update_page_markdown` | `updatePageMarkdown` |
+
+  (#412)
+
+- **External MCP: `import_page_markdown` removed, `update_page_markdown` added.**
+  The external `/mcp` surface no longer exposes `importPageMarkdown` (the
+  round-trip parser for a self-contained *exported* Docmost-Markdown file). In
+  its place it now exposes **`updatePageMarkdown`** — a plain-Markdown
+  full-body replace (`{pageId, content, title?}`) that pairs with
+  `updatePageJson`, re-imports the whole body (block ids regenerate) and
+  parses Docmost-flavoured markdown including `^[...]` inline footnotes.
+  *Migration:* MCP clients that called `importPageMarkdown` to overwrite a
+  page's body from Markdown should call `updatePageMarkdown` instead (pass the
+  markdown as `content`). Round-tripping an exported Docmost-Markdown file with
+  comment anchors/diagrams is no longer available on the external MCP surface;
+  export remains via `exportPageMarkdown`. The in-app AI agent is unaffected —
+  it keeps both `importPageMarkdown` and the renamed `updatePageMarkdown` (was
+  `updatePageContent`). The total MCP tool count is unchanged (−1 / +1). The
+  external names shown here are the post-#412 camelCase names. (#411)
+
+- **`getNode` now returns Markdown by default (was ProseMirror JSON).** The
+  block-level read/write tools default to Markdown so a block round trip is
+  `getNode` (markdown) → edit → `patchNode` (markdown). `getNode` now returns
+  `{ …, format: "markdown", markdown }` unless you pass `format: "json"` (which
+  restores the previous `{ …, node }` ProseMirror subtree); comment anchors —
+  including resolved ones — are preserved in the markdown so a write-back never
+  orphans a thread, and a node that cannot be a document top-level block
+  (`tableRow`/`tableCell`/`tableHeader` addressed via `#<index>`) auto-falls back
+  to JSON with `format: "json"` in the response. `patchNode`/`insertNode` gain a
+  `markdown` input alongside `node` (provide exactly one): the markdown fragment
+  may rewrite/insert several blocks at once and supports `^[...]` footnotes.
+  *Migration (external MCP clients only):* a client that consumed `getNode`'s
+  `node` field must now either read `markdown`, or pass `format: "json"` to keep
+  the old ProseMirror-JSON output. Released together with the `#411`/`#412`
+  breaking window so external configs break exactly once. (#413)
+
+- **The Prometheus `/metrics` listener now binds to `127.0.0.1` (loopback) by
+  default instead of `0.0.0.0` (all interfaces).** This closes an unauthenticated
+  endpoint that was previously reachable on every interface. **DEPLOY MIGRATION —
+  cross-container scraping breaks silently otherwise:** if your scraper runs in a
+  SEPARATE container and reaches the app as `docmost:9464` (the exact topology the
+  old `0.0.0.0` hardcode served), you MUST now set `METRICS_BIND=0.0.0.0` — and,
+  because that re-exposes the endpoint, also set `METRICS_TOKEN=<secret>` and
+  configure the scraper with a matching Bearer token. Without `METRICS_BIND`, the
+  scraper can no longer connect and metrics go dark with no error. See the
+  `METRICS_BIND` / `METRICS_TOKEN` block in `.env.example` for the migration.
+  Same-host (loopback) scrapers need no change. (#486)
+
 ### Added
 
 - **Place several images side by side in a row.** A new "Inline (side by
@@ -146,6 +263,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   by physical key position and matched against the commands; genuine Cyrillic
   search terms keep priority over remapped candidates, and short wrong-layout
   prefixes match by command title. (#283, #285, #287)
+- **Opt-in substring "lookup" search mode for agents.** `/api/search` gains an
+  additive, opt-in mode (guarded by a new `substring` flag) that matches literal
+  substrings of page titles and body text — so technical tokens the full-text
+  tokenizer mangles (`backup-srv.local`, `10.0.12.5`, `WB-MGE-30D86B`) are found
+  even when the FTS query is empty. It returns a location `path`, a windowed
+  `snippet` and a per-response relevance `score`, supports `titleOnly` and a
+  `parentPageId` subtree scope, and applies the page-level permission filter
+  before the limit. The web UI never sets `substring`, so its full-text search
+  behaviour is byte-for-byte unchanged. The leading-wildcard `LIKE` predicates
+  are backed by GIN trigram indexes on `LOWER(f_unaccent(title))` and
+  `LOWER(f_unaccent(text_content))` so lookups use a bitmap index scan instead of
+  a sequential scan. (#443)
+- **MCP `search` tool returns richer, agent-oriented results.** The external MCP
+  `search` response shape changes for the agent surface: each hit now carries
+  `pageId` (renamed from `id`), plus `path`, `snippet` and `score`; the
+  UI-oriented `spaceId`, `rank` and `highlight` fields are dropped. (#443)
 
 ### Changed
 
@@ -177,6 +310,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `tee()` branch of the stream result — a ~20-step, ~28k-chunk agent run
   retained ~1.7 GB and OOM'd the 2 GB JS heap. Streaming granularity is
   unchanged; the patch must be re-created if `ai` is ever bumped. (#184)
+
+- **The server no longer leaks a hung stream pipe on every mid-run client
+  disconnect.** The same `ai@6.0.134` pnpm patch now also fixes the SDK's
+  `writeToServerResponse`, which awaited only a `"drain"` event under
+  backpressure: when a client disconnected mid-write the socket never drained, so
+  the write loop parked forever, `response.end()` was unreachable, and the stream
+  reader plus buffered chunks were pinned until process restart (every mid-run
+  disconnect in autonomous mode leaked one). The patch races `"drain"` against
+  `"close"`/`"error"`, cancels the reader and ends the response on disconnect, and
+  swallows the fire-and-forget read rejection instead of crashing on an
+  unhandledRejection. (#486)
+
+- **A failed autonomous agent-run start no longer becomes an unstoppable ghost
+  run.** When `beginRun` failed for a transient reason (e.g. a DB-pool blip),
+  the turn previously continued with NO run row — invisible to `/stop`, not
+  aborted on disconnect, and able to slip a second run past the one-run-per-chat
+  gate, leaving an unstoppable run until restart. The turn now fails fast with an
+  honest `503 A_RUN_BEGIN_FAILED` before the first byte (no orphan state), and the
+  client shows a "temporary — please try again" message instead of a misleading
+  "provider not configured". (#486)
+
+- **A pathological draw.io graph can no longer wedge the whole server.** The ELK
+  auto-layout (`layout:"elk"`) ran elkjs synchronously on the main event loop, so
+  a graph at the node/edge cap blocked ALL HTTP/SSE/loopback traffic while it
+  churned — and the old `setTimeout` "timeout" could never fire because the same
+  thread was blocked. Layout now runs in a worker thread with the timeout enforced
+  by `worker.terminate()`; the main loop stays responsive. (#486)
+
+- **The `/health` Redis probe no longer leaks a client on every tick while Redis
+  is down.** It built a new `ioredis` client per probe and disconnected it only on
+  success, so during an outage each health tick added another forever-reconnecting
+  client (an unbounded handle leak). A single long-lived probe client is now
+  reused and closed on shutdown. (#486)
 - **Internal links in exported Markdown no longer lose their visible text.** A
   link whose target page name had no file extension (e.g. a bare title) was
   collapsed to empty text during export, producing an unclickable, label-less
@@ -253,6 +419,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   share); any other value now returns the generic "not found" instead of
   serving the page. (#218)
 
+- **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
+  internal page title or a stack fragment) and a provider error (which bundles the
+  provider `statusCode` and response body — potentially the internal baseUrl or
+  model name) were streamed verbatim to the anonymous reader over SSE. Errors are
+  now sanitized at the source: the share toolset collapses any unclassified tool
+  error to a safe generic string (safe, classified tool messages still pass
+  through for the model's self-correction), and the anonymous stream `onError`
+  maps provider failures to a fixed set of neutral strings — the full detail goes
+  only to the server log. A UI render gate is layered on top. (closes #394)
+
+- **The Prometheus `/metrics` endpoint can now require Bearer authentication and
+  is loopback-bound by default.** Previously it listened on all interfaces with no
+  auth. Setting `METRICS_TOKEN` requires every scrape to present
+  `Authorization: Bearer <token>` (compared in constant time), and the listener
+  defaults to `127.0.0.1` (see the Breaking Changes entry for the cross-container
+  migration). (#486)
+
 ## [0.94.0] - 2026-06-26
 
 This release makes AI chat durable and fast: assistant turns are persisted to

Dockerfile

@@ -45,6 +45,11 @@ COPY --from=builder /app/packages/editor-ext/dist /app/packages/editor-ext/dist
 COPY --from=builder /app/packages/editor-ext/package.json /app/packages/editor-ext/package.json
 COPY --from=builder /app/packages/mcp/build /app/packages/mcp/build
 COPY --from=builder /app/packages/mcp/package.json /app/packages/mcp/package.json
+# The mcp package reads its data files (drawio-presets.json, drawio-shape-index.json.gz)
+# at runtime via `new URL("../../data/…", import.meta.url)` relative to build/lib/*.js,
+# i.e. from packages/mcp/data/. tsc emits only build/, so ship data/ explicitly or
+# drawioFromGraph and the shape catalog die with ENOENT on packages/mcp/data/*.
+COPY --from=builder /app/packages/mcp/data /app/packages/mcp/data
 # mcp now depends on @docmost/prosemirror-markdown (workspace:*) and eager-imports
 # it at runtime (the in-app ai-chat DocmostClient loads build/index.js -> lib/
 # markdown-converter.js). Ship the built package + its manifest, or the prod
@@ -81,4 +86,14 @@ VOLUME ["/app/data/storage"]
 
 EXPOSE 3000
 
+# DEPLOY REQUIREMENT — SINGLE INSTANCE or STICKY SESSIONS (#449).
+# MCP content writes are serialized per page by an IN-PROCESS mutex, and the
+# stash_page blob store + cached collab sessions are RAM-only and process-local.
+# Running MULTIPLE replicas of this image behind a load balancer WITHOUT sticky
+# sessions silently breaks per-page write serialization (two replicas can lock
+# the same page at once) and makes stash_page blobs unreachable across replicas.
+# Run a SINGLE instance, or pin each page's traffic to one replica (sticky
+# sessions / consistent hashing on page id). There is deliberately no
+# cross-process lock yet — a conscious constraint. See .env.example (the "MCP
+# collaboration write path" block) and packages/mcp/README.md for details.
 CMD ["pnpm", "start"]

agent-roles-catalog/bundles/assistants/en.yaml

@@ -350,3 +350,109 @@ roles:
       a guess as a fact.
     autoStart: false
     launchMessage: null
+  - slug: call-summarizer
+    emoji: 📋
+    name: Meeting Summarizer
+    description: "Turns a raw automatic call transcript into meeting notes: agreements, action items, open questions."
+    instructions: |-
+      You are an assistant that turns a raw automatic call transcript into meeting notes. The notes are meant for people who were not on the call, and for participants who need to recall the decisions made and the "who does what" agreements.
+
+      ## Input data and its quirks
+
+      You are given an automatic transcript. It is imperfect; account for that:
+
+      - **Diarization is unreliable.** One label (e.g., "Speaker 1") may merge the lines of several people. Separate speakers by meaning: a change of position in an argument, being addressed by name, a reply to one's own line — signs of different people under one label. The "You" label is the recording owner; if others address them by name during the conversation, use the name. If attribution is unclear and you could not clarify it with the user (see "Clarifying questions") — write impersonally ("it was agreed", "one side proposed") or by role, rather than attributing words at random.
+      - **The "You" channel may contain unrelated lines** — the recording owner is talking to someone offline in parallel. Completely ignore lines unrelated to the call's topics.
+      - **Terms and names are distorted by speech recognition.** Technical terms and the names of protocols, products, and companies are often transcribed by ear in several variants (including phonetic misspellings: "wire guard" → WireGuard, "mod bus" → Modbus, "k-nips" → KNX). Normalize each concept to a single canonical spelling — the original Latin form for technical terms and brands.
+      - **Profanity and filler words** do not go into the notes.
+
+      ## Clarifying questions about participants
+
+      If you could not determine a participant's name and this hurts the notes (above all — assigning an owner to action items or attributing a key agreement), **ask the user before delivering the notes**. One compact question covering all unidentified people at once, with clues for identification — a role and a characteristic line:
+
+      > I couldn't identify two participants:
+      > — the one who handles design and promised to sketch logo options ("let me throw together some examples of what the logo could look like");
+      > — the one responsible for the hardware who explained the limitations of the E-Ink controller.
+      > Tell me their names — or say "leave it as is", and I'll refer to them by role.
+
+      Don't ask if: the name could not be determined but the participant does not appear in the agreements or action items; or the role by itself unambiguously identifies the person to the readers of the notes — then use the role ("the designer", "the firmware developer"). Don't ask more than one round of questions. Once you have the user's answer, deliver the notes right away: don't re-read the transcript from scratch and don't ask new questions — mark any unresolved remaining uncertainty with a role or with the note "(owner not identified)".
+
+      The question must not presume your merge hypothesis: if "one unidentified participant" ends up carrying disparate roles and tasks (design + a survey + logistics), don't ask "what's her name" — ask whether it is one person or several, and list the roles separately:
+
+      > I'm not sure whether this is one person or different people: (a) someone runs the survey and collects questions in Excel; (b) someone does the logo design; (c) someone is expecting displays to be delivered from customs. Is this one person or several, and what are their names?
+
+      ## Using web search
+
+      You have an internet search tool. Use it **only for normalization**: to verify the canonical spelling of a distorted term, product name, protocol, or company when the transcript's context is not enough. It is **forbidden** to add facts from the internet that were not in the conversation: the notes reflect only what was said on the call.
+
+      ## What to do
+
+      1. If the transcript looks cut off (a break mid-line, no wrap-up of the call) — read the remainder; one retry is enough, don't get stuck in a loop.
+      2. Mentally clean the transcript: separate the substance from noise, off-topic, and unrelated lines.
+      3. **Build a participant map** (an internal step, not included in the notes):
+         - write out all commitments taken and positions expressed — each as a separate record with the holder "unknown";
+         - write out all names by which someone is *addressed* (not mentioned in the third person), with the addressing quote;
+         - link a record to a name only when there is evidence: the address stands next to that holder's line, the holder replies to the address, or they are explicitly named as the owner ("Masha, why don't you sketch it"). **The absence of evidence is not a license for the most plausible guess: the record keeps its unknown holder.**
+         - two commitments belong to one person only if there is evidence linking them (one uninterrupted line, a self-reference "I'll also do…"). By default, the holders of different commitments are different people, even if both are "the woman leading the discussion".
+      4. For the remaining unknown holders, ask a clarifying question (see above) if they appear in the agreements or action items.
+      5. Extract the topics, agreements, commitments, and open questions.
+      6. Compose the notes strictly in the format below.
+
+      ## Notes format
+
+      ### Essence of the call
+      2–4 sentences: what the call was about and its main outcome. Below, on a single line — the participants: names and roles if determinable ("Masha — designer, Andrey, Vita — facilitator"); refer to unidentified ones by role.
+
+      ### Agreements
+      Substantive agreements by topic — what was decided and how things will work. Format of each item:
+
+      **Topic (2–4 words):** the essence of the agreement in one or two sentences; if a rationale was voiced — add it briefly ("…— to avoid drift between the converters"). If a status rather than an action was recorded for the topic ("already works", "accepted for work, a matter of priority", "fallback option") — state it.
+
+      This is for what both sides agreed to, including architectural and technical decisions, the division of responsibility ("X takes it on their side"), and chosen and rejected options. Proposals left without agreement don't belong here — their place is in "Open questions".
+
+      ### Action items
+      Concrete commitments taken. If most tasks share a common deadline — pull it into the subheading ("by the end of the week") and don't repeat it on every line. Line format:
+
+      - **Who:** what to do — deadline (if it differs from the common one or was named separately).
+
+      The owner is a name; if none was named, write "unassigned". Only explicit commitments go here ("let me look into it and send it over", "we'll draw it and show you"), not hypothetical "we could".
+
+      ### Open questions
+      Questions that were discussed but left unresolved and will clearly need a follow-up. For each — the essence and, if voiced, the sides' positions in one or two lines. Also here — proposals to which the other side did not agree.
+
+      ### Course of the discussion (by topic)
+      A section for those who were not on the call: the context the agreements grew out of. Group the substantive discussions by topic (not by chronology). For each topic: which options and arguments were voiced, who objected to whom and about what, what it came to. Preserve:
+
+      - the arguments **for and against**, including counterarguments to the decisions taken;
+      - **rejected options with the reasons** ("voice over 2.4 GHz rejected: short range, a second modem needed");
+      - **vivid phrasings and metaphors**, if they carry the meaning of a position ("to play the guitar more often — put it closer to the couch"), — one line each, without retelling the whole remark.
+
+      The section's length depends on the type of call: for a decision-making call (discussed — decided — dispersed) it is short or absent, the whole substance is already in "Agreements". For a discussion-heavy sync this is the largest section by volume. Don't duplicate the wording of the agreements — this section holds the *why* and the *alternatives considered* on the way to them.
+
+      ### Deferred / off-agenda
+      Topics deliberately left untouched for now, and ideas "for the future".
+
+      ## Rules
+
+      - **Don't invent anything.** Every agreement and action item must rest on a specific place in the transcript. If a fact is ambiguous due to transcript quality, mark it: "(uncertain per the transcript)".
+      - **Verify names before delivering.** For every name you use as an owner or the author of a position, find grounds in the transcript: this person is addressed by name, and the address links to their lines. A name merely mentioned in passing in the third person (including in unrelated off-topic) is not grounds to consider them a participant. Subjective confidence is not grounds either: no address — no name; ask the user or use a role. Red flag: one name owns nearly all action items across different roles (design, a survey, specifications) — double-check whether you merged several people into one.
+      - **An agreement ≠ a proposal.** "What if we do X?" is an idea. "Yes, let's", "agreed", "we already discussed this and agreed", "accepted, a matter of priority" — an agreement. Tell them apart.
+      - **Preserve the rationales.** If a decision was explained ("an MQTT broker is more reliable under VPN blocking"), that is one of the most valuable parts of the notes — include the rationale as a single phrase.
+      - **Don't bloat.** The notes should read in 2–3 minutes. Omit empty sections entirely.
+      - **The language of the notes = the main language of the call.** Technical terms — in their canonical spelling (usually Latin).
+      - **Don't evaluate the participants** and don't comment on the quality of the discussion.
+      - The output is the notes only, with no preambles or meta-comments, apart from targeted uncertainty marks.
+
+      ## Style example (excerpt)
+
+      **Agreements**
+
+      - **MicroSerial as the single conversion point:** reuse MicroSerial (the ESP Modbus→MQTT converter) for MQTT and, down the line, KNX — to avoid drift between different converters.
+      - **Remote access:** the primary option is an external MQTT broker (more reliable under VPN blocking, encryption support is needed); WireGuard — as a fallback.
+
+      **Action items (by the end of the week)**
+
+      - **Vladislav:** test MicroSerial with the HES3 template on the MGE, send over the firmware — today or tomorrow.
+      - **Zhenya:** reply about the hardware timeline.
+    autoStart: true
+    launchMessage: Take the current page into work — it contains the call transcript. If there is none, ask the user where the transcript is.

agent-roles-catalog/bundles/assistants/ru.yaml

@@ -349,3 +349,109 @@ roles:
       a guess as a fact.
     autoStart: false
     launchMessage: null
+  - slug: call-summarizer
+    emoji: 📋
+    name: Конспектор созвонов
+    description: "Превращает сырую автоматическую расшифровку созвона в конспект: договорённости, action items, открытые вопросы."
+    instructions: |-
+      Ты — ассистент, который превращает сырую автоматическую расшифровку созвона в конспект. Конспект предназначен для тех, кто не был на созвоне, и для участников, которым нужно вспомнить принятые решения и договорённости «кто что делает».
+
+      ## Входные данные и их особенности
+
+      Тебе даётся автоматическая расшифровка. Она несовершенна, учитывай это:
+
+      - **Диаризация ненадёжна.** Под одной меткой (например, «Speaker 1») могут быть слиты реплики нескольких людей. Разделяй говорящих по смыслу: смена позиции в споре, обращение по имени, ответ на собственную реплику — признаки разных людей под одной меткой. Метка «You» — владелец записи; если в разговоре к нему обращаются по имени, используй имя. Если атрибуция неясна и её не удалось уточнить у пользователя (см. «Уточняющие вопросы») — пиши обезличенно («договорились», «одна из сторон предложила») или по роли, а не приписывай слова наугад.
+      - **Канал «You» может содержать посторонние реплики** — владелец записи параллельно разговаривает с кем-то офлайн. Реплики, не связанные с темами созвона, полностью игнорируй.
+      - **Термины и названия искажены распознаванием речи.** Технические термины, названия протоколов, продуктов и компаний часто записаны на слух в нескольких вариантах (в т.ч. англицизмы кириллицей: «вайргард» → WireGuard, «мадбас» → Modbus, «кныипс» → KNX). Приводи каждое понятие к одному каноническому написанию — в оригинальной латинице для технических терминов и брендов.
+      - **Мат и слова-паразиты** в конспект не переносятся.
+
+      ## Уточняющие вопросы об участниках
+
+      Если не удалось определить имя участника, а это мешает конспекту (в первую очередь — назначить исполнителя в action items или атрибутировать ключевую договорённость), **спроси пользователя перед выдачей конспекта**. Один компактный вопрос на всех неопознанных сразу, с зацепками для опознания — ролью и характерной репликой:
+
+      > Не смог определить двух участников:
+      > — тот, кто занимается дизайном и обещал накидать варианты лого («давай накидаю примеры, как может выглядеть лого»);
+      > — тот, кто отвечает за железо и объяснял ограничения E-Ink контроллера.
+      > Подскажи имена — или скажи «оставь как есть», и я обозначу их по ролям.
+
+      Не спрашивай, если: имя не удалось определить, но участник не фигурирует в договорённостях и action items; или роль сама по себе однозначно идентифицирует человека для читателей конспекта — тогда используй роль («дизайнер», «разработчик прошивки»). Не задавай больше одного раунда вопросов. Получив ответ пользователя, сразу выдавай конспект: не перечитывай расшифровку заново и не задавай новых вопросов — неразрешённые остатки неопределённости обозначай ролью или пометкой «(исполнитель не установлен)».
+
+      Вопрос не должен презюмировать твою гипотезу о слиянии: если «один неопознанный участник» получается носителем разнородных ролей и задач (дизайн + опрос + логистика), не спрашивай «как её зовут» — спроси, один это человек или несколько, и перечисли роли по отдельности:
+
+      > Не уверен, один это человек или разные: (а) кто-то ведёт опрос и собирает вопросы в Excel; (б) кто-то делает дизайн лого; (в) кому-то должны привезти дисплеи с таможни. Это один человек или несколько, и как их зовут?
+
+      ## Использование веб-поиска
+
+      У тебя есть инструмент поиска в интернете. Используй его **только для нормализации**: проверить каноническое написание искажённого термина, названия продукта, протокола или компании, когда контекста расшифровки недостаточно. **Запрещено** добавлять в конспект факты из интернета, которых не было в разговоре: конспект отражает только то, что прозвучало на созвоне.
+
+      ## Что нужно сделать
+
+      1. Если расшифровка выглядит оборванной (обрыв на середине реплики, нет завершения созвона) — дочитай остаток; одной повторной попытки достаточно, не зацикливайся.
+      2. Мысленно очисти расшифровку: отдели содержательную часть от шума, оффтопа и посторонних реплик.
+      3. **Построй карту участников** (внутренний шаг, в конспект не выводится):
+         - выпиши все взятые обязательства и выраженные позиции — каждую как отдельную запись с носителем «неизвестно»;
+         - выпиши все имена, по которым к кому-то *обращаются* (не упоминают в третьем лице), с цитатой-обращением;
+         - связывай запись с именем только при наличии улики: обращение стоит рядом с репликой этого носителя, носитель отвечает на обращение, или его прямо называют исполнителем («давай ты, Маша, накидаешь»). **Отсутствие улики — не повод для наиболее правдоподобной догадки: запись остаётся с неизвестным носителем.**
+         - два обязательства принадлежат одному человеку только если есть улика связи между ними (одна непрерывная реплика, самоссылка «я ещё сделаю…»). По умолчанию носители разных обязательств — разные люди, даже если оба «женщина, ведущая обсуждение».
+      4. По оставшимся неизвестным носителям задай уточняющий вопрос (см. ниже), если они фигурируют в договорённостях или action items.
+      5. Выдели темы, договорённости, обязательства и открытые вопросы.
+      6. Составь конспект строго по формату ниже.
+
+      ## Формат конспекта
+
+      ### Суть созвона
+      2–4 предложения: о чём созванивались и главный итог. Ниже одной строкой — участники: имена и роли, если определимы («Маша — дизайнер, Андрей, Вита — ведущая»); неопознанных обозначь по роли.
+
+      ### Договорённости
+      Содержательные соглашения по темам — что решили и как будет устроено. Формат каждого пункта:
+
+      **Тема (2–4 слова):** суть договорённости одним-двумя предложениями; если прозвучало обоснование — добавь его коротко («…— чтобы избежать дрейфа между конвертерами»). Если по теме зафиксирован статус, а не действие («уже работает», «принято в работу, вопрос приоритета», «резервный вариант») — укажи его.
+
+      Сюда попадает то, с чем согласились обе стороны, включая архитектурные и технические решения, распределение зон ответственности («X берёт на свою сторону»), выбранные и отвергнутые варианты. Предложения, оставшиеся без согласия, сюда не входят — им место в «Открытых вопросах».
+
+      ### Action items
+      Конкретные взятые обязательства. Если у большинства задач общий срок — вынеси его в подзаголовок («к концу недели») и не повторяй в каждой строке. Формат строки:
+
+      - **Кто:** что сделать — срок (если отличается от общего или назван отдельно).
+
+      Исполнитель — имя; если не назван, пиши «не назначен». Сюда попадают только явные обязательства («давайте я посмотрю и скину», «мы нарисуем и покажем»), а не гипотетические «можно было бы».
+
+      ### Открытые вопросы
+      Вопросы, которые обсуждались, но остались без решения, и явно потребуют возврата. Для каждого — суть и, если были, позиции сторон в одну-две строки. Сюда же — предложения, на которые вторая сторона не дала согласия.
+
+      ### Ход обсуждения (по темам)
+      Раздел для тех, кто не был на созвоне: контекст, из которого выросли договорённости. Сгруппируй содержательные обсуждения по темам (не по хронологии). По каждой теме: какие варианты и аргументы прозвучали, что кому возразили, к чему пришли. Сохраняй:
+
+      - аргументы **за и против**, включая контраргументы к принятым решениям;
+      - **отвергнутые варианты с причинами** («голос на 2.4 GHz отвергнут: малая дальность, нужен второй модем»);
+      - **яркие формулировки и метафоры**, если они несут смысл позиции («чтобы чаще играть на гитаре — поставь её ближе к дивану»), — одной строкой, без пересказа всей реплики.
+
+      Объём раздела зависит от типа созвона: для решенческого созвона (обсудили — решили — разошлись) он короткий или отсутствует, вся суть уже в «Договорённостях». Для дискуссионного синка это основной по объёму раздел. Не дублируй формулировки договорённостей — здесь живёт то, *почему* и *через какие альтернативы* к ним пришли.
+
+      ### Отложено / вне повестки
+      Темы, которые сознательно решили не трогать сейчас, и идеи «на будущее».
+
+      ## Правила
+
+      - **Ничего не выдумывай.** Каждая договорённость и action item должны опираться на конкретное место в расшифровке. Если факт неоднозначен из-за качества расшифровки, помечай: «(неточно по расшифровке)».
+      - **Проверка имён перед выдачей.** Для каждого имени, которое ты используешь как исполнителя или автора позиции, найди в расшифровке основание: к этому человеку обращаются по имени, и обращение связывается с его репликами. Имя, лишь мельком упомянутое в третьем лице (в т.ч. в постороннем оффтопе), — не основание считать его участником. Субъективная уверенность основанием не является: нет обращения — нет имени, спрашивай пользователя или используй роль. Красный флаг: одно имя владеет почти всеми action items разных ролей (дизайн, опрос, спецификации) — перепроверь, не слил ли ты нескольких людей в одного.
+      - **Договорённость ≠ предложение.** «А может, сделаем X?» — идея. «Да, давайте», «согласен», «мы это уже обсудили и согласились», «принято, вопрос приоритета» — договорённость. Различай.
+      - **Сохраняй обоснования.** Если решение объяснили («MQTT-брокер надёжнее при блокировках VPN»), это одна из самых ценных частей конспекта — включай обоснование одной фразой.
+      - **Не раздувай.** Конспект должен читаться за 2–3 минуты. Пустые разделы опускай целиком.
+      - **Язык конспекта = основной язык созвона.** Технические термины — в каноническом написании (обычно латиницей).
+      - **Не оценивай участников** и не комментируй качество обсуждения.
+      - На выходе — только конспект, без преамбул и мета-комментариев, кроме точечных пометок неуверенности.
+
+      ## Пример стиля (фрагмент)
+
+      **Договорённости**
+
+      - **MicroSerial как единая точка конвертации:** переиспользовать микросериал (ESP-конвертер Modbus→MQTT) для MQTT и в перспективе KNX — чтобы избежать дрейфа между разными конвертерами.
+      - **Удалённый доступ:** основной вариант — внешний MQTT-брокер (надёжнее при блокировках VPN, нужна поддержка шифрования); WireGuard — как резерв.
+
+      **Action items (к концу недели)**
+
+      - **Владислав:** проверить MicroSerial с шаблоном HES3 на MGE, скинуть прошивку — сегодня-завтра.
+      - **Женя:** ответить по срокам железа.
+    autoStart: true
+    launchMessage: Возьми в работу текущую страницу — на ней расшифровка созвона. Если её нет, спроси у пользователя, где расшифровка.

agent-roles-catalog/index.yaml

@@ -21,16 +21,18 @@ bundles:
         version: 8
       - slug: narrator
         version: 2
-  - id: research
+  - id: assistants
     name:
-      ru: Исследование
-      en: Research
+      ru: Ассистенты
+      en: Assistants
     description:
-      ru: Глубокое исследование темы с подготовкой отчёта.
-      en: Deep research on a topic with a prepared report.
+      ru: Ассистенты общего назначения
+      en: General-purpose assistants
     languages:
       - ru
       - en
     roles:
       - slug: researcher
-        version: 8
+        version: 9
+      - slug: call-summarizer
+        version: 1

agent-roles-catalog/scripts/content-hashes.json

@@ -1,4 +1,8 @@
 {
+  "call-summarizer": {
+    "version": 1,
+    "hash": "edba0c5ac5e27460f73efd361ee4e7cb743a085ae141f3b649e9d306e5929553"
+  },
   "fact-checker": {
     "version": 6,
     "hash": "6bb22a9e5a5079b5cb287b5b26addbd36b9afeb7c9508287dcad9343fc53d685"
@@ -16,8 +20,8 @@
     "hash": "cef39fed321779631ddd1077fcba53399adf0e48b301df281c71eb042610900d"
   },
   "researcher": {
-    "version": 8,
-    "hash": "0e76efa180c3e443c8856b8787e9643923d10486b373ce078c12dc16eb04611b"
+    "version": 9,
+    "hash": "880047f6a8612d420c77c03d9cc6308a25b2cd6f84647da9df9bae0e22bd5e4d"
   },
   "structural-editor": {
     "version": 4,

apps/client/package.json

@@ -13,6 +13,7 @@
   },
   "dependencies": {
     "@ai-sdk/react": "^3.0.208",
+    "@braintree/sanitize-url": "7.1.2",
     "@atlaskit/pragmatic-drag-and-drop": "1.8.1",
     "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "2.1.5",
     "@atlaskit/pragmatic-drag-and-drop-flourish": "2.0.15",
@@ -98,6 +99,7 @@
     "typescript": "5.9.3",
     "typescript-eslint": "8.57.1",
     "vite": "8.0.5",
+    "vite-plugin-compression2": "2.5.3",
     "vitest": "4.1.6"
   }
 }

apps/client/src/App.tsx

@@ -1,38 +1,72 @@
+import { lazy, Suspense } from "react";
 import { Navigate, Route, Routes } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
+import { Error404 } from "@/components/ui/error-404.tsx";
+import Layout from "@/components/layouts/global/layout.tsx";
+import { useTrackOrigin } from "@/hooks/use-track-origin";
+
+// ShareLayout is route-split: its ShareShell chrome pulls in the table of
+// contents (and thus TipTap), so keeping it out of the eager graph removes the
+// editor engine from startup for authenticated users too.
+const ShareLayout = lazy(
+  () => import("@/features/share/components/share-layout.tsx"),
+);
+
+// Auth / entry pages stay eager: they are the first paint for an unauthenticated
+// visitor (e.g. /login) and are already small, so code-splitting them would only
+// add a cold-chunk round trip to the most common cold-start path.
 import SetupWorkspace from "@/pages/auth/setup-workspace.tsx";
 import LoginPage from "@/pages/auth/login";
-import Home from "@/pages/dashboard/home";
-import Page from "@/pages/page/page";
-import AccountSettings from "@/pages/settings/account/account-settings";
-import WorkspaceMembers from "@/pages/settings/workspace/workspace-members";
-import WorkspaceSettings from "@/pages/settings/workspace/workspace-settings";
-import AiSettings from "@/pages/settings/workspace/ai-settings";
-import Groups from "@/pages/settings/group/groups";
-import GroupInfo from "./pages/settings/group/group-info";
-import Spaces from "@/pages/settings/space/spaces.tsx";
-import { Error404 } from "@/components/ui/error-404.tsx";
-import AccountPreferences from "@/pages/settings/account/account-preferences.tsx";
-import SpaceHome from "@/pages/space/space-home.tsx";
-import PageRedirect from "@/pages/page/page-redirect.tsx";
-import Layout from "@/components/layouts/global/layout.tsx";
 import InviteSignup from "@/pages/auth/invite-signup.tsx";
 import ForgotPassword from "@/pages/auth/forgot-password.tsx";
 import PasswordReset from "./pages/auth/password-reset";
-import SharedPage from "@/pages/share/shared-page.tsx";
-import Shares from "@/pages/settings/shares/shares.tsx";
-import ShareLayout from "@/features/share/components/share-layout.tsx";
+import PageRedirect from "@/pages/page/page-redirect.tsx";
 import ShareRedirect from "@/pages/share/share-redirect.tsx";
-import { useTrackOrigin } from "@/hooks/use-track-origin";
-import SpacesPage from "@/pages/spaces/spaces.tsx";
-import SpaceTrash from "@/pages/space/space-trash.tsx";
-import FavoritesPage from "@/pages/favorites/favorites-page";
-import LabelPage from "@/pages/label/label-page";
+
+// Heavy / leaf pages are route-split with React.lazy so their code (most
+// importantly the whole TipTap editor + KaTeX + lowlight grammars + drawio that
+// the page editor and the readonly share editor pull in) is fetched only when
+// the matching route is actually visited. The <Suspense> boundaries live inside
+// each Layout (around its <Outlet/>), so the app shell stays mounted while a
+// route chunk loads.
+const Home = lazy(() => import("@/pages/dashboard/home"));
+const Page = lazy(() => import("@/pages/page/page"));
+const SpaceHome = lazy(() => import("@/pages/space/space-home.tsx"));
+const SpaceTrash = lazy(() => import("@/pages/space/space-trash.tsx"));
+const SpacesPage = lazy(() => import("@/pages/spaces/spaces.tsx"));
+const FavoritesPage = lazy(() => import("@/pages/favorites/favorites-page"));
+const LabelPage = lazy(() => import("@/pages/label/label-page"));
+const SharedPage = lazy(() => import("@/pages/share/shared-page.tsx"));
+
+const AccountSettings = lazy(
+  () => import("@/pages/settings/account/account-settings"),
+);
+const AccountPreferences = lazy(
+  () => import("@/pages/settings/account/account-preferences.tsx"),
+);
+const WorkspaceSettings = lazy(
+  () => import("@/pages/settings/workspace/workspace-settings"),
+);
+const AiSettings = lazy(() => import("@/pages/settings/workspace/ai-settings"));
+const WorkspaceMembers = lazy(
+  () => import("@/pages/settings/workspace/workspace-members"),
+);
+const Groups = lazy(() => import("@/pages/settings/group/groups"));
+const GroupInfo = lazy(() => import("./pages/settings/group/group-info"));
+const Spaces = lazy(() => import("@/pages/settings/space/spaces.tsx"));
+const Shares = lazy(() => import("@/pages/settings/shares/shares.tsx"));
 
 export default function App() {
   useTrackOrigin();
 
   return (
-    <>
+    <Suspense
+      fallback={
+        <Center h="100vh">
+          <Loader size="sm" />
+        </Center>
+      }
+    >
       <Routes>
         <Route index element={<Navigate to="/home" />} />
         <Route path={"/login"} element={<LoginPage />} />
@@ -83,6 +117,6 @@ export default function App() {
 
         <Route path="*" element={<Error404 />} />
       </Routes>
-    </>
+    </Suspense>
   );
 }

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

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { isChunkLoadError } 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
+// recovery UI, no reload). A false negative on a real chunk failure re-blanks the
+// app; a false positive would auto-reload on an ordinary error. Pin both sides.
+describe("isChunkLoadError", () => {
+  it("detects the ChunkLoadError name", () => {
+    expect(isChunkLoadError({ name: "ChunkLoadError", message: "x" })).toBe(true);
+  });
+
+  it.each([
+    "Failed to fetch dynamically imported module: https://x/assets/index-abc.js",
+    "error loading dynamically imported module",
+    "Importing a module script failed.",
+  ])("detects the dynamic-import failure message %#", (message) => {
+    expect(isChunkLoadError({ name: "TypeError", message })).toBe(true);
+  });
+
+  it("is case-insensitive on the message", () => {
+    expect(
+      isChunkLoadError({ message: "FAILED TO FETCH DYNAMICALLY IMPORTED MODULE" }),
+    ).toBe(true);
+  });
+
+  it.each([
+    null,
+    undefined,
+    {},
+    { name: "TypeError", message: "Cannot read properties of undefined" },
+    { message: "Network request failed" },
+    new Error("some ordinary render error"),
+  ])("returns false for a non-chunk error %#", (err) => {
+    expect(isChunkLoadError(err)).toBe(false);
+  });
+});

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

@@ -0,0 +1,71 @@
+import { ReactNode } from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { Button, Center, Stack, Text } from "@mantine/core";
+
+const RELOAD_FLAG = "chunk-reload-attempted";
+
+// Heuristic detection of a failed dynamic import. Since the code-splitting work,
+// every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
+// replaces the hashed chunks, a tab left open on the old index.html requests a
+// chunk URL that now 404s, and React.lazy rejects. Browsers / Vite surface these
+// with a ChunkLoadError name or one of these messages.
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error) return false;
+  const name = (error as { name?: string }).name ?? "";
+  const message = (error as { message?: string }).message ?? "";
+  return (
+    name === "ChunkLoadError" ||
+    /Failed to fetch dynamically imported module/i.test(message) ||
+    /error loading dynamically imported module/i.test(message) ||
+    /Importing a module script failed/i.test(message)
+  );
+}
+
+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.
+  try {
+    if (sessionStorage.getItem(RELOAD_FLAG)) return;
+    sessionStorage.setItem(RELOAD_FLAG, "1");
+  } catch {
+    // sessionStorage unavailable (private mode / disabled): skip the automatic
+    // reload rather than risk an unguarded loop; the fallback UI still recovers.
+    return;
+  }
+  window.location.reload();
+}
+
+// Root-level boundary that sits ABOVE every route-level Suspense boundary so a
+// lazy route/component chunk failure is caught here instead of unmounting the
+// whole tree into a blank white screen. Per-feature ErrorBoundaries (page.tsx,
+// transclusion, page-embed) remain in place underneath for their local errors.
+export function ChunkLoadErrorBoundary({ children }: { children: ReactNode }) {
+  return (
+    <ErrorBoundary
+      onError={handleError}
+      fallbackRender={({ error }) => {
+        const chunk = isChunkLoadError(error);
+        return (
+          <Center h="100vh" p="md">
+            <Stack align="center" gap="sm" maw={420}>
+              <Text fw={600}>
+                {chunk ? "A new version is available" : "Something went wrong"}
+              </Text>
+              <Text size="sm" c="dimmed" ta="center">
+                {chunk
+                  ? "Please reload the page to load the latest version."
+                  : "An unexpected error occurred. Reloading the page may help."}
+              </Text>
+              <Button onClick={() => window.location.reload()}>Reload</Button>
+            </Stack>
+          </Center>
+        );
+      }}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}

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

@@ -1,9 +1,10 @@
 import { AppShell, Container } from "@mantine/core";
-import React, { useEffect, useRef, useState } from "react";
+import React, { Suspense, useEffect, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import SettingsSidebar from "@/components/settings/settings-sidebar.tsx";
-import { useAtom } from "jotai";
+import { useAtom, useAtomValue } from "jotai";
+import { aiChatWindowOpenAtom } from "@/features/ai-chat/atoms/ai-chat-atom.ts";
 import {
   APP_NAVBAR_ID,
   NAVBAR_COLLAPSE_BREAKPOINT,
@@ -14,8 +15,6 @@ import {
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
 import { SpaceSidebar } from "@/features/space/components/sidebar/space-sidebar.tsx";
 import { AppHeader } from "@/components/layouts/global/app-header.tsx";
-import Aside from "@/components/layouts/global/aside.tsx";
-import AiChatWindow from "@/features/ai-chat/components/ai-chat-window.tsx";
 import GitmostGlobalBridge from "@/features/editor/gitmost/gitmost-global-bridge.tsx";
 import classes from "./app-shell.module.css";
 import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
@@ -23,6 +22,21 @@ import GlobalSidebar from "@/components/layouts/global/global-sidebar.tsx";
 import { ASIDE_PANEL_ID } from "@/hooks/use-toggle-aside.tsx";
 import { MAIN_CONTENT_ID, SkipToMain } from "@/components/ui/skip-to-main.tsx";
 
+// Lazily load the AI chat window so the AI SDK runtime it pulls in is fetched
+// only after the user first opens the chat, instead of for every authenticated
+// user on load. The window itself renders null while closed, so there is no
+// behavior difference — it simply is not mounted until first opened.
+const AiChatWindow = React.lazy(
+  () => import("@/features/ai-chat/components/ai-chat-window.tsx"),
+);
+
+// The right aside hosts the comment panel and table of contents, both of which
+// pull in TipTap. It only ever renders on page routes, so lazy-loading it keeps
+// the whole editor engine out of the eager global-shell startup graph.
+const Aside = React.lazy(
+  () => import("@/components/layouts/global/aside.tsx"),
+);
+
 export default function GlobalAppShell({
   children,
 }: {
@@ -37,6 +51,15 @@ export default function GlobalAppShell({
   const [isResizing, setIsResizing] = useState(false);
   const sidebarRef = useRef(null);
 
+  // Latch: once the AI chat window has been opened, keep it mounted so an
+  // in-flight stream is never torn down. Before the first open the AI chat chunk
+  // is never fetched.
+  const aiChatOpen = useAtomValue(aiChatWindowOpenAtom);
+  const [aiChatEverOpened, setAiChatEverOpened] = useState(false);
+  useEffect(() => {
+    if (aiChatOpen) setAiChatEverOpened(true);
+  }, [aiChatOpen]);
+
   const startResizing = React.useCallback((mouseDownEvent) => {
     mouseDownEvent.preventDefault();
     setIsResizing(true);
@@ -67,14 +90,20 @@ export default function GlobalAppShell({
   );
 
   useEffect(() => {
-    //https://codesandbox.io/p/sandbox/kz9de
+    // Attach the global mousemove/mouseup only WHILE resizing (started on the
+    // handle's mousedown via startResizing → isResizing=true) and detach on
+    // mouseup (stopResizing → isResizing=false). Previously these listeners were
+    // attached for the whole app lifetime, so every mouse move over the app ran
+    // the resize handler.
+    // https://codesandbox.io/p/sandbox/kz9de
+    if (!isResizing) return;
     window.addEventListener("mousemove", resize);
     window.addEventListener("mouseup", stopResizing);
     return () => {
       window.removeEventListener("mousemove", resize);
       window.removeEventListener("mouseup", stopResizing);
     };
-  }, [resize, stopResizing]);
+  }, [isResizing, resize, stopResizing]);
 
   const location = useLocation();
   const isSettingsRoute = location.pathname.startsWith("/settings");
@@ -160,13 +189,21 @@ export default function GlobalAppShell({
                   : undefined
           }
         >
-          <Aside />
+          <Suspense fallback={null}>
+            <Aside />
+          </Suspense>
         </AppShell.Aside>
       )}
     </AppShell>
-    {/* Floating AI chat window. Mounted once globally; it is position: fixed
-        and self-hides when closed, so its place in the tree is not critical. */}
-    <AiChatWindow />
+    {/* Floating AI chat window. Mounted once globally on first open; it is
+        position: fixed and self-hides when closed, so its place in the tree is
+        not critical. Kept mounted after the first open so a live stream is not
+        aborted. */}
+    {aiChatEverOpened && (
+      <Suspense fallback={null}>
+        <AiChatWindow />
+      </Suspense>
+    )}
       {/* Global gitmost native bridge: registers listSpaces / listPages /
           createPageWithRecording on window.gitmost so the native host can
           create a page with a recording even when no page editor is open. */}

apps/client/src/components/layouts/global/layout.tsx

@@ -1,5 +1,7 @@
+import { Suspense, useEffect } from "react";
 import { UserProvider } from "@/features/user/user-provider.tsx";
 import { Outlet, useParams } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
 import GlobalAppShell from "@/components/layouts/global/global-app-shell.tsx";
 import { SearchSpotlight } from "@/features/search/components/search-spotlight.tsx";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -8,10 +10,39 @@ export default function Layout() {
   const { spaceSlug } = useParams();
   const { data: space } = useGetSpaceBySlugQuery(spaceSlug);
 
+  // Warm the (now route-split) editor chunk during idle time on authenticated
+  // routes, so the first navigation to a page renders from cache instead of a
+  // cold chunk fetch. Best-effort: gated on requestIdleCallback and never blocks
+  // startup — the dynamic import mirrors the App.tsx route lazy loader so both
+  // resolve to the same chunk.
+  useEffect(() => {
+    const ric =
+      typeof window !== "undefined" && (window as any).requestIdleCallback;
+    const warm = () => {
+      // Best-effort prefetch: a failed warm-up (offline, stale 404) is harmless
+      // and must not surface as an unhandledrejection.
+      void import("@/pages/page/page").catch(() => {});
+    };
+    if (ric) {
+      const id = ric(warm);
+      return () => (window as any).cancelIdleCallback?.(id);
+    }
+    const timer = setTimeout(warm, 2000);
+    return () => clearTimeout(timer);
+  }, []);
+
   return (
     <UserProvider>
       <GlobalAppShell>
-        <Outlet />
+        <Suspense
+          fallback={
+            <Center h="60vh">
+              <Loader size="sm" />
+            </Center>
+          }
+        >
+          <Outlet />
+        </Suspense>
       </GlobalAppShell>
       <SearchSpotlight spaceId={space?.id} />
     </UserProvider>

apps/client/src/components/ui/emoji-picker.tsx

@@ -5,7 +5,7 @@ import {
   Button,
   useMantineColorScheme,
 } from "@mantine/core";
-import { useClickOutside, useDisclosure, useWindowEvent } from "@mantine/hooks";
+import { useClickOutside, useDisclosure } from "@mantine/hooks";
 import { Suspense } from "react";
 import { useTranslation } from "react-i18next";
 
@@ -57,14 +57,22 @@ function EmojiPicker({
     [dropdown, target],
   );
 
-  // We need this because the default Mantine popover closeOnEscape does not work
-  useWindowEvent("keydown", (event) => {
-    if (opened && event.key === "Escape") {
-      event.stopPropagation();
-      event.preventDefault();
-      handlers.close();
-    }
-  });
+  // We need this because the default Mantine popover closeOnEscape does not work.
+  // Attach the global keydown ONLY while the picker is open (every tree row
+  // renders an EmojiPicker, so an always-on window listener meant ~20-30 idle
+  // keydown handlers firing on each keystroke).
+  useEffect(() => {
+    if (!opened) return;
+    const handleKeydown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.stopPropagation();
+        event.preventDefault();
+        handlers.close();
+      }
+    };
+    window.addEventListener("keydown", handleKeydown);
+    return () => window.removeEventListener("keydown", handleKeydown);
+  }, [opened, handlers]);
 
   // emoji-mart's built-in autoFocus calls .focus() without preventScroll, which
   // makes the browser scroll every scrollable ancestor of the search input to

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

@@ -36,7 +36,7 @@ import {
   desktopSidebarAtom,
   mobileSidebarAtom,
 } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import {
   pageEditorAtom,
   readOnlyEditorAtom,
@@ -245,7 +245,9 @@ export default function AiChatWindow() {
   // left partly off-screen).
   const [geom, setGeom] = useAtom(aiChatWindowGeomAtom);
 
-  const { data: chats } = useAiChatsQuery();
+  // Gated on windowOpen: the chat list is only needed once the window is open,
+  // so a closed window issues no chat-list request/refetch on navigation.
+  const { data: chats } = useAiChatsQuery(windowOpen);
   // Roles for the new-chat picker (any member may list them). Only fetched while
   // the window is open.
   const { data: roles } = useAiRolesQuery(windowOpen);
@@ -291,6 +293,10 @@ export default function AiChatWindow() {
         Date.now() - lastActivityAtRef.current < DEGRADED_POLL_IDLE_MAX_MS
           ? 2500
           : false,
+      // #344: gate on windowOpen too — no message history is fetched (and no
+      // degraded poll runs) while the window is closed; it loads when the window
+      // opens with an active chat.
+      windowOpen,
     );
 
   // #430: re-stamp the activity clock whenever the polled rows change while the
@@ -336,7 +342,7 @@ export default function AiChatWindow() {
   // reads/writes via its CASL-enforced page tools using the id.
   const pageRouteMatch = useMatch("/s/:spaceSlug/p/:pageSlug");
   const pageSlug = pageRouteMatch?.params?.pageSlug;
-  const { data: openPageData } = usePageQuery({
+  const { data: openPageData } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const openPage = openPageData

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

@@ -28,7 +28,10 @@ const h = vi.hoisted(() => ({
         body: Record<string, unknown>;
       }) => { body: Record<string, unknown> };
       prepareReconnectToStreamRequest?: () => { api?: string };
-      fetch?: (input: unknown, init?: { method?: string }) => Promise<unknown>;
+      fetch?: (
+        input: unknown,
+        init?: { method?: string; body?: unknown },
+      ) => Promise<unknown>;
     },
   },
 }));
@@ -200,6 +203,290 @@ describe("ChatThread — send now (#198)", () => {
   });
 });
 
+// #486: the final onFinish -> flushNext() must be gated on the live-mount flag.
+// A clean onFinish can land AFTER the thread unmounts (New-chat / chat-switch
+// mid-stream — the async attach/resume settles late); flushing then dequeues and
+// re-POSTs a queued message from an abandoned thread (a "ghost" send).
+describe("ChatThread — onFinish flush gated on mount (#486)", () => {
+  beforeEach(resetState);
+  afterEach(cleanup);
+
+  it("a clean onFinish WHILE MOUNTED flushes the queued message (control)", () => {
+    renderThread();
+    fireEvent.click(screen.getByTestId("queue-btn")); // enqueue "queued text"
+    expect(h.state.sendMessage).not.toHaveBeenCalled();
+
+    act(() => {
+      h.state.onFinish?.({
+        message: { id: "a", role: "assistant", parts: [] },
+        isAbort: false,
+        isDisconnect: false,
+        isError: false,
+      });
+    });
+    // Mounted: the queue flushes normally.
+    expect(h.state.sendMessage).toHaveBeenCalledWith({ text: "queued text" });
+  });
+
+  it("a clean onFinish AFTER unmount does NOT flush (no ghost send)", () => {
+    const { unmount } = renderThread();
+    fireEvent.click(screen.getByTestId("queue-btn")); // enqueue "queued text"
+    h.state.sendMessage.mockClear();
+
+    // Chat switched away mid-stream: the streamer unmounts...
+    unmount();
+    // ...and a late, clean onFinish lands on the abandoned thread.
+    act(() => {
+      h.state.onFinish?.({
+        message: { id: "a", role: "assistant", parts: [] },
+        isAbort: false,
+        isDisconnect: false,
+        isError: false,
+      });
+    });
+    // Gated on mountedRef: NOTHING is sent from the dead thread.
+    expect(h.state.sendMessage).not.toHaveBeenCalled();
+  });
+});
+
+// #396: in autonomous mode a live sendNow must additionally request the
+// AUTHORITATIVE server stop of the detached run (a local abort is only a client
+// disconnect the server ignores) and arm a bounded 409 retry so the re-POST
+// converges once the one-active-run slot frees. Legacy mode is unchanged.
+describe("ChatThread — send now server-stop + supersede retry (#396)", () => {
+  beforeEach(resetState);
+  afterEach(cleanup);
+
+  // A settled assistant tail => no mount resume (attemptResumeRef false), so the
+  // "Send now" button is visible for the NEW local streaming turn while
+  // autonomous runs are enabled.
+  const settledTail = () => [
+    row("u1", "user", undefined, "hi"),
+    row("a1", "assistant", "succeeded", "done"),
+  ];
+
+  it("autonomous: sendNow during a live stream calls onServerStop with the chat id", () => {
+    const { onServerStop } = renderThread({
+      autonomousRunsEnabled: true,
+      initialRows: settledTail(),
+    });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    expect(h.state.stop).toHaveBeenCalledTimes(1);
+    expect(onServerStop).toHaveBeenCalledWith("c1");
+  });
+
+  it("legacy (autonomous off): sendNow does NOT call onServerStop and does NOT retry the send", async () => {
+    const { onServerStop } = renderThread({
+      autonomousRunsEnabled: false,
+      initialRows: settledTail(),
+    });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+    expect(onServerStop).not.toHaveBeenCalled();
+
+    // The supersede retry must NOT be armed: a POST that 409s is returned as-is
+    // (single fetch, no retry).
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(
+        new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+          status: 409,
+        }),
+      );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+
+  it("armed supersede send retries 409 A_RUN_ALREADY_ACTIVE and succeeds once the slot frees", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    // Arm the retry by performing a live sendNow (autonomous branch sets the ref).
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    const fetchMock = vi
+      .fn()
+      // First POST: the old detached run still holds the slot -> 409.
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+          status: 409,
+        }),
+      )
+      // Retry: the server stop settled the old run -> 200.
+      .mockResolvedValueOnce(new Response("ok", { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(res.status).toBe(200);
+  });
+
+  it("supersede retry is one-shot: a later send (ref cleared) does NOT retry a 409", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now")); // arms the one-shot
+
+    // First armed send: immediately succeeds, consuming the arm.
+    let fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response("ok", { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await act(async () => {
+      await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      });
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A subsequent send is NOT armed -> a 409 is returned as-is (no retry).
+    fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+        status: 409,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+
+  it("supersede retry is bounded: exhaustion surfaces the 409 error", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    // Every attempt 409s -> after 4 attempts the last 409 surfaces.
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+        status: 409,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    // 4 attempts total (1 immediate + 3 backoff retries), then give up.
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+    expect(res.status).toBe(409);
+  });
+
+  it("armed supersede send does NOT retry a non-409 status", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response("boom", { status: 500 }));
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(500);
+  });
+
+  // Strand-path regression: sendNow arms the supersede retry, but if the promoted
+  // head is removed before the abort's onFinish lands, flushNext() sends nothing
+  // (returns false) and NO re-POST consumes the arm. The arm must be disarmed on
+  // that no-send branch so the NEXT unrelated NORMAL send does not inherit it and
+  // silently retry a genuine 409 (e.g. a legitimate two-tab conflict) 4x instead
+  // of surfacing it immediately.
+  it("strand-path: a stranded supersede arm (flushNext no-send) does NOT retry a later normal 409", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    // Arm the retry via a live autonomous sendNow (promotes the head + arms).
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    // Remove the promoted head BEFORE the abort lands, so flushNext() returns
+    // false (no POST) and the arm would strand without the disarm fix.
+    fireEvent.click(screen.getByLabelText("Remove queued message"));
+
+    // The abort's onFinish now takes the flushOnAbortRef branch, calls flushNext()
+    // which finds an empty queue and returns false -> the no-send disarm must run.
+    act(() => {
+      h.state.onFinish?.({
+        message: { id: "a1", role: "assistant", parts: [] },
+        isAbort: true,
+        isDisconnect: false,
+        isError: false,
+      });
+    });
+    // No re-POST was sent (nothing to flush).
+    expect(h.state.sendMessage).not.toHaveBeenCalled();
+
+    // A subsequent NORMAL send that 409s must be returned as-is (exactly 1 fetch):
+    // the stranded arm must NOT cause the genuine 409 to be retried.
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(
+        new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+          status: 409,
+        }),
+      );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+
+  it("armed supersede send does NOT retry a 409 with a different (non-A_RUN_ALREADY_ACTIVE) body", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: "SOMETHING_ELSE" }), {
+        status: 409,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+});
+
 // #388: the editor selection is snapshotted at send time and nested inside
 // openPage on the wire. The getter is read live from a ref, so each send ships a
 // fresh snapshot.

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

@@ -70,6 +70,36 @@ const RECONNECT_MAX_ATTEMPTS = 5;
 // Backoff before attempt N (1-based): 1s, 2s, 4s, 8s, 16s.
 const RECONNECT_BASE_DELAY_MS = 1000;
 
+// #396: bounded retry for the "Interrupt and send now" re-send when it races the
+// authoritative server stop of the just-superseded detached run. The re-POST can
+// arrive before the old run has released the one-active-run slot, so the server
+// returns 409 A_RUN_ALREADY_ACTIVE. The server stop guarantees the slot frees, so
+// a few short backoffs converge. 4 total attempts: attempt 1 fires immediately,
+// then these are the waits BEFORE attempts 2, 3 and 4 (150ms, 300ms, 600ms). If
+// all 4 attempts 409, the last 409 surfaces (the banner) — acceptable per #396.
+const SUPERSEDE_RETRY_DELAYS_MS = [150, 300, 600];
+// The server error code that means "another run is already active for this chat".
+const A_RUN_ALREADY_ACTIVE = "A_RUN_ALREADY_ACTIVE";
+
+/**
+ * #396: defensively decide whether a 409 response is the one-active-run gate
+ * rejection (code A_RUN_ALREADY_ACTIVE) vs. some other 409. Reads a CLONE so the
+ * original response body stays intact for the caller when it is returned as-is.
+ * Any parse failure or unexpected shape => false (do NOT retry).
+ */
+async function isRunAlreadyActive(response: Response): Promise<boolean> {
+  try {
+    const body = (await response.clone().json()) as unknown;
+    return (
+      typeof body === "object" &&
+      body !== null &&
+      (body as { code?: unknown }).code === A_RUN_ALREADY_ACTIVE
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** The page the user is currently viewing, sent as chat context. */
 export interface OpenPageContext {
   id: string;
@@ -326,6 +356,26 @@ export default function ChatThread({
   const flushOnAbortRef = useRef(false);
   const interruptNextSendRef = useRef(false);
 
+  // #396: one-shot arm for the bounded 409 A_RUN_ALREADY_ACTIVE retry on the
+  // "Interrupt and send now" re-send in autonomous mode. sendNow triggers the
+  // authoritative server stop of the detached run, but that stop and the
+  // onFinish->flushNext re-POST race: the new POST can hit the one-active-run
+  // gate before the old detached run has settled, yielding a spurious 409. When
+  // this ref is armed, the transport's send path retries that 409 with a short
+  // bounded backoff (the server stop guarantees convergence). A normal send (ref
+  // not armed) must STILL fail a 409 instantly (e.g. a genuine two-tab conflict).
+  //
+  // INVARIANT: sendNow arms this only to be consumed by the ONE re-POST that
+  // flushNext fires from onFinish. But that re-POST does not always happen (the
+  // promoted head may be gone, the finish may be a resumed turn, or the arm may
+  // race a stale finish). To keep the arm strictly one-shot it is disarmed on
+  // EVERY path where the paired interrupt one-shots (flushOnAbortRef /
+  // interruptNextSendRef) are cleared without a POST: the transport POST branch
+  // consumes it (read-and-clear), the onFinish `!flushNext()` no-send branch
+  // clears it, and the isStreaming-defuse effect clears it symmetrically. So it
+  // can never leak into a later, unrelated send and retry that send's genuine 409.
+  const supersedeRetryRef = useRef(false);
+
   // #234 F5: the user pressed Stop while streaming a BRAND-NEW chat whose server
   // chat id has not been adopted yet (the `start` chunk carrying it hadn't landed
   // when Stop was pressed). A local SSE abort alone does NOT stop the DETACHED
@@ -382,7 +432,43 @@ export default function ChatThread({
           }`,
         }),
         fetch: async (input: RequestInfo | URL, init: RequestInit = {}) => {
-          if ((init.method ?? "GET") !== "GET") return fetch(input, init); // send path untouched
+          if ((init.method ?? "GET") !== "GET") {
+            // Send path (POST). #396: read-and-clear the one-shot supersede arm
+            // here so it is strictly scoped to THIS send. When unarmed, behave
+            // exactly as before — a single fetch, a 409 surfaces instantly (a
+            // genuine two-tab conflict must NOT be retried).
+            const supersede = supersedeRetryRef.current;
+            supersedeRetryRef.current = false;
+            if (!supersede) return fetch(input, init);
+            // Buffer a ReadableStream body once so each retry can replay it.
+            // DefaultChatTransport sends the body as a JSON STRING (replayable as
+            // is), but guard defensively in case a future SDK streams it.
+            let sendInit = init;
+            if (init.body instanceof ReadableStream) {
+              const buffered = await new Response(init.body).arrayBuffer();
+              sendInit = { ...init, body: buffered };
+            }
+            // Bounded retry: attempt 1 fires immediately, then wait between
+            // attempts per SUPERSEDE_RETRY_DELAYS_MS. Retry ONLY on a real
+            // 409 A_RUN_ALREADY_ACTIVE; any other status/body is returned as-is.
+            for (let attempt = 0; ; attempt++) {
+              const response = await fetch(input, sendInit);
+              if (
+                response.status !== 409 ||
+                attempt >= SUPERSEDE_RETRY_DELAYS_MS.length ||
+                !(await isRunAlreadyActive(response))
+              ) {
+                return response;
+              }
+              // The old detached run has not released the one-active-run slot
+              // yet; the server stop we requested guarantees it will, so back off
+              // and re-POST (the 409 fired before the user message was persisted,
+              // so re-POSTing is safe — no duplicate rows).
+              await new Promise((r) =>
+                setTimeout(r, SUPERSEDE_RETRY_DELAYS_MS[attempt]),
+              );
+            }
+          }
           // Reconnect GET: the SDK passes no AbortSignal, so wire our own controller
           // for observer Stop / unmount abort.
           const controller = new AbortController();
@@ -562,13 +648,24 @@ export default function ChatThread({
         setStopNotice(null);
         // If the promoted head vanished (e.g. the user removed it before the
         // abort landed) flushNext sends nothing — clear the one-shot interrupt
-        // tag so it can't leak onto the next unrelated send. On a real send the
-        // tag is consumed by prepareSendMessagesRequest and stays untouched.
-        if (!flushNext()) interruptNextSendRef.current = false;
+        // tag AND the #396 supersede arm so neither can leak onto the next
+        // unrelated send (no re-POST will consume the arm here). On a real send
+        // the tag is consumed by prepareSendMessagesRequest and the arm by the
+        // transport POST branch, so both stay untouched then.
+        if (!flushNext()) {
+          interruptNextSendRef.current = false;
+          supersedeRetryRef.current = false;
+        }
         return;
       }
       if (isAbort || isDisconnect || isError) return;
-      flushNext();
+      // Gate the final flush on the live-mount flag (#486): a clean onFinish can
+      // land AFTER this thread unmounted (a New-chat / chat-switch mid-stream —
+      // the async attach/resume settles late). Flushing then dequeues and POSTs a
+      // queued message from an abandoned thread — a "ghost" send / ghost chat.
+      // Every other queue side effect already guards on mountedRef; this last one
+      // was the gap.
+      if (mountedRef.current) flushNext();
     },
     // `onError` runs in addition to `onFinish` (which ai@6 also calls on error).
     // Log the raw failure here for devtools; the UI shows a friendly classified
@@ -873,6 +970,30 @@ export default function ChatThread({
         setQueue(promoteToHead(queuedRef.current, id));
         flushOnAbortRef.current = true;
         interruptNextSendRef.current = true;
+        // #396: in autonomous mode the turn is a DETACHED run — a local stop()
+        // is only a client disconnect the server ignores, so the run keeps going.
+        // The onFinish->flushNext re-POST would then hit the one-active-run gate
+        // and get a spurious 409 A_RUN_ALREADY_ACTIVE. Mirror handleStop: request
+        // the AUTHORITATIVE server stop so the detached run settles, and arm the
+        // one-shot bounded 409 retry BEFORE stop() so the re-send converges once
+        // the slot frees. Read chatId live from chatIdRef (adopted at the `start`
+        // chunk). If it is not known yet (brand-new chat, first moment of its
+        // first turn), defer the server stop via stopPendingRef exactly as
+        // handleStop does — the onServerChatId adoption effect fires it once the
+        // id lands; the retry stays armed so the re-send still converges then.
+        if (autonomousRunsEnabled) {
+          supersedeRetryRef.current = true; // arm the bounded 409 retry
+          if (chatIdRef.current) {
+            onServerStop?.(chatIdRef.current);
+          } else {
+            // Same #234-F5 sub-window limitation documented in handleStop: if the
+            // local abort below cancels the reader before the `start` chunk lands,
+            // the adoption effect never runs and the deferred stop never fires. Not
+            // a regression; at minimum we don't strand refs (the isStreaming effect
+            // defuses stopPendingRef on the next turn start).
+            stopPendingRef.current = true;
+          }
+        }
         stop(); // -> onFinish({ isAbort: true }) flushes the promoted head
       } else {
         // Nothing to interrupt: just send it now (no interrupt note).
@@ -884,7 +1005,7 @@ export default function ChatThread({
         sendMessageRef.current?.({ text: msg.text });
       }
     },
-    [setQueue, stop, setResumedTurnPair],
+    [setQueue, stop, setResumedTurnPair, autonomousRunsEnabled, onServerStop],
   );
 
   // Stop the current turn. ALWAYS abort the local SSE (`stop()`) so the composer
@@ -944,6 +1065,13 @@ export default function ChatThread({
       setStopNotice(null);
       flushOnAbortRef.current = false;
       interruptNextSendRef.current = false;
+      // #396: symmetric with the other one-shot interrupt flags — defuse a stale
+      // supersede arm that was set but whose expected re-POST never fired (the
+      // turn finished in the same tick as the click, or the promoted head was
+      // gone), so it can never leak into this (or a later) turn's send and retry
+      // that send's genuine 409. A legit arm is consumed by the transport POST
+      // branch before this new turn streams, so this does not clobber it.
+      supersedeRetryRef.current = false;
       // #234 F5: a new turn is starting — drop any pending deferred-stop from a
       // previous turn that never adopted an id, so it can never fire against this
       // (or a later) unrelated turn's run. A deferred stop for the CURRENT turn is

apps/client/src/features/ai-chat/components/message-item.tsx

@@ -47,6 +47,13 @@ interface MessageItemProps {
    * agent's raw query/argument text.
    */
   showInput?: boolean;
+  /**
+   * Forwarded to ToolCallCard: whether a failed tool card renders its raw
+   * errorText. Defaults to true (internal chat). The public share passes false so
+   * internal detail in a tool error is never painted (belt to the server-side
+   * byte sanitization).
+   */
+  showErrors?: boolean;
   /**
    * Neutralize internal/relative markdown links in the rendered answer (drop
    * their href so they become inert text). Defaults to false (internal chat,
@@ -125,6 +132,7 @@ function MessageItem({
   message,
   showCitations = true,
   showInput = true,
+  showErrors = true,
   neutralizeInternalLinks = false,
   assistantName,
   turnStreaming = false,
@@ -219,6 +227,7 @@ function MessageItem({
               part={part as unknown as ToolUiPart}
               showCitations={showCitations}
               showInput={showInput}
+              showErrors={showErrors}
             />
           );
         }
@@ -284,6 +293,7 @@ export function arePropsEqual(
     prev.signature === next.signature &&
     prev.showCitations === next.showCitations &&
     prev.showInput === next.showInput &&
+    prev.showErrors === next.showErrors &&
     prev.neutralizeInternalLinks === next.neutralizeInternalLinks &&
     prev.assistantName === next.assistantName &&
     // The turn-end flip re-renders every row once (cheap, terminal event) —

apps/client/src/features/ai-chat/components/message-list.tsx

@@ -32,6 +32,12 @@ interface MessageListProps {
    * doesn't see the agent's raw query/argument text.
    */
   showInput?: boolean;
+  /**
+   * Forwarded to MessageItem -> ToolCallCard: whether a failed tool card renders
+   * its raw errorText. Defaults to true (internal chat). The public share passes
+   * false so internal detail in a tool error is never painted.
+   */
+  showErrors?: boolean;
   /**
    * Forwarded to MessageItem: neutralize internal/relative markdown links in
    * the rendered answers (drop their href so they render as inert text).
@@ -127,6 +133,7 @@ export default function MessageList({
   emptyState,
   showCitations = true,
   showInput = true,
+  showErrors = true,
   neutralizeInternalLinks = false,
   assistantName,
 }: MessageListProps) {
@@ -217,6 +224,7 @@ export default function MessageList({
             signature={messageSignature(message)}
             showCitations={showCitations}
             showInput={showInput}
+            showErrors={showErrors}
             neutralizeInternalLinks={neutralizeInternalLinks}
             assistantName={assistantName}
             // Turn-level liveness, gated to the TAIL row: only the tail message

apps/client/src/features/ai-chat/components/tool-call-card.tsx

@@ -30,6 +30,16 @@ interface ToolCallCardProps {
    * the extra summary line, leaving the card (the action log) intact.
    */
   showInput?: boolean;
+  /**
+   * Whether to render the tool's raw errorText on a failed call. Defaults to true
+   * (the internal chat, where the operator may debug). The public share passes
+   * false: a tool error string can carry internal detail (an internal page title,
+   * a stack fragment, a provider message). This is the RENDER gate only — the
+   * authoritative fix also sanitizes the bytes server-side (see
+   * PublicShareChatToolsService.forShare), so a share reader never receives raw
+   * error text over the wire, not just never sees it painted (#394).
+   */
+  showErrors?: boolean;
 }
 
 /**
@@ -41,6 +51,7 @@ export default function ToolCallCard({
   part,
   showCitations = true,
   showInput = true,
+  showErrors = true,
 }: ToolCallCardProps) {
   const { t } = useTranslation();
   const toolName = getToolName(part);
@@ -74,7 +85,7 @@ export default function ToolCallCard({
         </Text>
       )}
 
-      {state === "error" && part.errorText && (
+      {state === "error" && showErrors && part.errorText && (
         <Text size="xs" c="red" mt={2}>
           {part.errorText}
         </Text>

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

@@ -53,8 +53,12 @@ export const AI_CHAT_MESSAGES_RQ_KEY = (chatId: string) => [
   chatId,
 ];
 
-/** Paginated list of the current user's chats (auto-loads further pages). */
-export function useAiChatsQuery() {
+/**
+ * Paginated list of the current user's chats (auto-loads further pages).
+ * `enabled` (default true) lets the AI chat window skip fetching while it is
+ * closed — the list is only needed once the window is open.
+ */
+export function useAiChatsQuery(enabled: boolean = true) {
   const query = useInfiniteQuery({
     queryKey: AI_CHATS_RQ_KEY,
     queryFn: ({ pageParam }) => getAiChats({ cursor: pageParam, limit: 50 }),
@@ -63,6 +67,7 @@ export function useAiChatsQuery() {
       lastPage.meta.hasNextPage
         ? (lastPage.meta.nextCursor ?? undefined)
         : undefined,
+    enabled,
   });
 
   const data = useMemo<IPagination<IAiChat> | undefined>(() => {
@@ -93,6 +98,9 @@ export function useAiChatMessagesQuery(
   // follow the detached run to settle. The callback form lives in AiChatWindow;
   // threaded here verbatim so this query owns the polling. Undefined => no poll.
   refetchInterval?: number | false | (() => number | false),
+  // #344: gate the query so a backgrounded/hidden window stops issuing refetches
+  // and duplicating work. Defaults to enabled to preserve existing call-sites.
+  enabled: boolean = true,
 ) {
   const query = useInfiniteQuery({
     queryKey: AI_CHAT_MESSAGES_RQ_KEY(chatId ?? ""),
@@ -103,7 +111,7 @@ export function useAiChatMessagesQuery(
       lastPage.meta.hasNextPage
         ? (lastPage.meta.nextCursor ?? undefined)
         : undefined,
-    enabled: !!chatId,
+    enabled: !!chatId && enabled,
     refetchInterval,
   });
 

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

@@ -23,6 +23,25 @@ describe("describeChatError", () => {
     });
   });
 
+  it("classifies an A_RUN_BEGIN_FAILED 503 as a temporary run-start failure, NOT provider-not-configured (#486)", () => {
+    // The FULL real body the server writes for a beginRun failure: a
+    // ServiceUnavailableException(object) whose response is serialized verbatim
+    // onto the raw socket, self-describing statusCode 503 + the run-start code.
+    const body =
+      '{"message":"Could not start the agent run. This is usually temporary — please try again.","code":"A_RUN_BEGIN_FAILED","statusCode":503}';
+    expect(describeChatError(body, t)).toEqual({
+      title: "Could not start the run",
+      detail:
+        "The agent run could not be started. This is usually temporary — please try again.",
+    });
+    // ORDER GUARD: even though the body ALSO carries statusCode 503 (which the
+    // generic branch matches), the A_RUN_BEGIN_FAILED branch runs first, so it is
+    // never mislabeled "AI provider not configured".
+    expect(describeChatError(body, t).title).not.toBe(
+      "AI provider not configured",
+    );
+  });
+
   it("classifies a dropped connection (ECONNRESET) as a lost-connection error", () => {
     expect(
       describeChatError("Cannot connect to API: read ECONNRESET", t).title,

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

@@ -24,6 +24,21 @@ export function describeChatError(
 ): ChatErrorView {
   const msg = message ?? "";
 
+  // Our own "could not start the run" gate (A_RUN_BEGIN_FAILED, #486): a 503
+  // whose body carries this code is a TEMPORARY server-side failure while
+  // starting the run (e.g. a DB-pool blip), NOT an unconfigured provider. It MUST
+  // be matched STRICTLY BEFORE the generic 503 branch below, which would
+  // otherwise mislabel it "The AI provider is not configured" and tell the user
+  // to call an admin instead of just retrying.
+  if (/"code"\s*:\s*"A_RUN_BEGIN_FAILED"/.test(msg)) {
+    return {
+      title: t("Could not start the run"),
+      detail: t(
+        "The agent run could not be started. This is usually temporary — please try again.",
+      ),
+    };
+  }
+
   if (/"statusCode"\s*:\s*403\b/.test(msg)) {
     return {
       title: t("AI chat is disabled"),

apps/client/src/features/comment/components/comment-content-view.test.tsx

@@ -15,6 +15,7 @@ vi.mock("@/features/comment/components/comment-editor", () => ({
 // case renders in isolation.
 vi.mock("@/features/page/queries/page-query.ts", () => ({
   usePageQuery: () => ({ data: undefined, isLoading: false, isError: false }),
+  usePageMetaQuery: () => ({ data: undefined, isLoading: false, isError: false }),
 }));
 vi.mock("@/features/share/queries/share-query.ts", () => ({
   useSharePageQuery: () => ({ data: undefined }),

apps/client/src/features/comment/components/comment-list-with-tabs.tsx

@@ -22,7 +22,7 @@ import CommentEditor from "@/features/comment/components/comment-editor";
 import CommentActions from "@/features/comment/components/comment-actions";
 import { useFocusWithin } from "@mantine/hooks";
 import { IComment } from "@/features/comment/types/comment.types.ts";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
 import { useTranslation } from "react-i18next";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -56,7 +56,7 @@ export function buildChildrenByParent(
 function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
-  const { data: page } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
+  const { data: page } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
   const {
     data: comments,
     isLoading: isCommentsLoading,

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

@@ -1,5 +1,8 @@
 import { atom } from "jotai";
-import { Editor } from "@tiptap/core";
+// Type-only: these atoms only hold an Editor reference for typing. A value
+// 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 { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";
 

apps/client/src/features/editor/components/audio/audio-menu.tsx

@@ -46,6 +46,13 @@ export function AudioMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes unless an audio node is active. The menu
+      // only shows for an active audio node (shouldShow), so the null state while
+      // inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("audio")) {
+        return null;
+      }
+
       const audioAttrs = ctx.editor.getAttributes("audio");
 
       return {

apps/client/src/features/editor/components/callout/callout-menu.tsx

@@ -43,8 +43,15 @@ export function CalloutMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip the per-type isActive() probes unless a callout is
+      // active. The menu only shows for an active callout (shouldShow), so the
+      // null state while inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("callout")) {
+        return null;
+      }
+
       return {
-        isCallout: ctx.editor.isActive("callout"),
+        isCallout: true,
         isInfo: ctx.editor.isActive("callout", { type: "info" }),
         isNote: ctx.editor.isActive("callout", { type: "note" }),
         isSuccess: ctx.editor.isActive("callout", { type: "success" }),

apps/client/src/features/editor/components/code-block/code-block-view.tsx

@@ -22,6 +22,12 @@ export default function CodeBlockView(props: NodeViewProps) {
   const [isSelected, setIsSelected] = useState(false);
 
   useEffect(() => {
+    // #343 PART 6: `isSelected` only drives the mermaid source's visibility (the
+    // `hidden` prop below). For every non-mermaid code block it is never read,
+    // so skip the per-block `selectionUpdate` listener entirely — otherwise N
+    // code blocks each add a global listener + a setState on every caret move.
+    if (language !== "mermaid") return;
+
     const updateSelection = () => {
       const { state } = editor;
       const { from, to } = state.selection;
@@ -32,11 +38,14 @@ export default function CodeBlockView(props: NodeViewProps) {
       setIsSelected(isNodeSelected);
     };
 
+    // Initialize on attach so switching a block's language to "mermaid" reflects
+    // the current selection immediately (the listener was not running before).
+    updateSelection();
     editor.on("selectionUpdate", updateSelection);
     return () => {
       editor.off("selectionUpdate", updateSelection);
     };
-  }, [editor, getPos(), node.nodeSize]);
+  }, [editor, getPos(), node.nodeSize, language]);
 
   function changeLanguage(language: string) {
     setLanguageValue(language);

apps/client/src/features/editor/components/drawio/drawio-menu-lazy.tsx

@@ -0,0 +1,16 @@
+import { lazy, Suspense } from "react";
+import { EditorMenuProps } from "@/features/editor/components/table/types/types.ts";
+
+// Lazily load the drawio bubble menu so it is split out of the editor chunk and
+// fetched only when an editable editor is mounted (mirrors excalidraw-menu-lazy).
+const DrawioMenu = lazy(
+  () => import("@/features/editor/components/drawio/drawio-menu.tsx"),
+);
+
+export default function DrawioMenuLazy(props: EditorMenuProps) {
+  return (
+    <Suspense fallback={null}>
+      <DrawioMenu {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/drawio/drawio-view-lazy.tsx

@@ -0,0 +1,17 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the drawio node view so the heavy react-drawio embed runtime is
+// split into its own chunk and fetched only when a drawio diagram is actually
+// rendered (mirrors excalidraw-view-lazy).
+const DrawioView = lazy(
+  () => import("@/features/editor/components/drawio/drawio-view.tsx"),
+);
+
+export default function DrawioViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={null}>
+      <DrawioView {...props} />
+    </Suspense>
+  );
+}

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

@@ -1,5 +1,7 @@
 import type { Editor } from "@tiptap/react";
 import { useEditorState } from "@tiptap/react";
+import { undoDepth, redoDepth } from "@tiptap/pm/history";
+import { yUndoPluginKey } from "@tiptap/y-tiptap";
 
 export interface ToolbarState {
   isBold: boolean;
@@ -16,14 +18,45 @@ export interface ToolbarState {
   canRedo: boolean;
 }
 
-// Undo/redo come from either StarterKit's history or the Yjs collaboration
-// history extension. During the brief moment a page is rendered with the
-// static editor (mainExtensions only, undoRedo disabled), neither is loaded
-// and editor.can().undo/redo is undefined.
-function safeCan(editor: Editor, command: "undo" | "redo"): boolean {
-  const can = editor.can() as Record<string, unknown>;
-  const fn = can[command];
-  return typeof fn === "function" ? (fn as () => boolean)() : false;
+// Undo/redo availability, computed WITHOUT `editor.can().undo()/.redo()`.
+//
+// `editor.can()` runs the command as a dry-run (building a throwaway state +
+// transaction) — the most expensive work in this selector, and it ran on every
+// keystroke (and every REMOTE keystroke under collaboration). Instead we read
+// the history stack depth directly, which is a cheap plugin-state lookup and
+// mirrors exactly what the undo/redo commands themselves check:
+//
+//  - Collaboration (Yjs): the yjs UndoManager's undo/redo stack lengths — the
+//    same `undoStack.length === 0` / `redoStack.length === 0` guard the
+//    Collaboration extension's undo/redo commands use.
+//  - Plain history (templates / non-collab): prosemirror-history's undoDepth /
+//    redoDepth, which back the UndoRedo extension.
+//
+// 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.
+function historyAvailability(editor: Editor): {
+  canUndo: boolean;
+  canRedo: boolean;
+} {
+  const state = editor.state;
+
+  // Collaboration history (Yjs) takes precedence when present.
+  const yState = yUndoPluginKey.getState(state) as
+    | { undoManager?: { undoStack: unknown[]; redoStack: unknown[] } }
+    | undefined;
+  if (yState?.undoManager) {
+    return {
+      canUndo: yState.undoManager.undoStack.length > 0,
+      canRedo: yState.undoManager.redoStack.length > 0,
+    };
+  }
+
+  // Plain prosemirror-history (returns 0 when the history plugin is absent).
+  return {
+    canUndo: undoDepth(state) > 0,
+    canRedo: redoDepth(state) > 0,
+  };
 }
 
 export function useToolbarState(editor: Editor | null): ToolbarState | null {
@@ -31,6 +64,7 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
     editor,
     selector: (ctx) => {
       if (!ctx.editor) return null;
+      const { canUndo, canRedo } = historyAvailability(ctx.editor);
       return {
         isBold: ctx.editor.isActive("bold"),
         isItalic: ctx.editor.isActive("italic"),
@@ -42,8 +76,8 @@ export function useToolbarState(editor: Editor | null): ToolbarState | null {
         isBulletList: ctx.editor.isActive("bulletList"),
         isOrderedList: ctx.editor.isActive("orderedList"),
         isTaskList: ctx.editor.isActive("taskList"),
-        canUndo: safeCan(ctx.editor, "undo"),
-        canRedo: safeCan(ctx.editor, "redo"),
+        canUndo,
+        canRedo,
       };
     },
   });

apps/client/src/features/editor/components/image/image-menu.tsx

@@ -38,6 +38,14 @@ export function ImageMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip the expensive per-keystroke work (getAttributes + the
+      // alignment isActive() probes) unless an image is actually active. The
+      // menu is only shown when an image is active (see shouldShow), so a null
+      // state while inactive is never rendered — behavior is unchanged.
+      if (!ctx.editor.isActive("image")) {
+        return null;
+      }
+
       const imageAttrs = ctx.editor.getAttributes("image");
 
       return {

apps/client/src/features/editor/components/link/link-view.tsx

@@ -24,7 +24,7 @@ import classes from "./link.module.css";
 import { useTranslation } from "react-i18next";
 import { INTERNAL_LINK_REGEX } from "@/lib/constants";
 import { LinkEditorPanel } from "@/features/editor/components/link/link-editor-panel.tsx";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { useSharePageQuery } from "@/features/share/queries/share-query.ts";
 import { buildSharedPageUrl } from "@/features/page/page.utils.ts";
 import { extractPageSlugId } from "@/lib";
@@ -83,7 +83,7 @@ export default function LinkView(props: MarkViewProps) {
   const isPopoverVisible = popoverState !== "closed";
   const activeView = isPopoverVisible ? popoverState : lastOpenState.current;
 
-  const { data: linkedPage } = usePageQuery({
+  const { data: linkedPage } = usePageMetaQuery({
     pageId: isPopoverVisible && slugId && !isShareRoute ? slugId : null,
   });
 

apps/client/src/features/editor/components/math/math-block-lazy.tsx

@@ -0,0 +1,19 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the KaTeX-backed block math view so the katex chunk is fetched
+// only when a document actually contains a math node (mirrors the mermaid/
+// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
+// crashing or blocking the whole editor: while it loads we render the raw
+// LaTeX source as a node-sized placeholder.
+const MathBlockView = lazy(
+  () => import("@/features/editor/components/math/math-block.tsx"),
+);
+
+export default function MathBlockViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={<div data-katex="true">{props.node.attrs.text}</div>}>
+      <MathBlockView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/math/math-inline-lazy.tsx

@@ -0,0 +1,19 @@
+import { lazy, Suspense } from "react";
+import { NodeViewProps } from "@tiptap/react";
+
+// Lazily load the KaTeX-backed inline math view so the katex chunk is fetched
+// only when a document actually contains a math node (mirrors the mermaid/
+// excalidraw lazy pattern). The local Suspense keeps a slow katex chunk from
+// crashing or blocking the whole editor: while it loads we render the raw
+// LaTeX source as a node-sized placeholder.
+const MathInlineView = lazy(
+  () => import("@/features/editor/components/math/math-inline.tsx"),
+);
+
+export default function MathInlineViewLazy(props: NodeViewProps) {
+  return (
+    <Suspense fallback={<span data-katex="true">{props.node.attrs.text}</span>}>
+      <MathInlineView {...props} />
+    </Suspense>
+  );
+}

apps/client/src/features/editor/components/mention/mention-list.tsx

@@ -25,7 +25,7 @@ import { IconFileDescription, IconPlus } from "@tabler/icons-react";
 import { useSpaceQuery } from "@/features/space/queries/space-query.ts";
 import { useParams } from "react-router-dom";
 import { v7 as uuid7 } from "uuid";
-import { useAtom } from "jotai";
+import { useAtom, useSetAtom, useStore } from "jotai";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import {
   MentionListProps,
@@ -34,7 +34,7 @@ import {
 import { IPage } from "@/features/page/types/page.types";
 import {
   useCreatePageMutation,
-  usePageQuery,
+  usePageMetaQuery,
 } from "@/features/page/queries/page-query";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom";
 import { treeModel } from "@/features/page/tree/model/tree-model";
@@ -50,12 +50,16 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
   const [countAnnouncement, setCountAnnouncement] = useState("");
   const [selectionAnnouncement, setSelectionAnnouncement] = useState("");
   const { pageSlug, spaceSlug } = useParams();
-  const { data: page } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
+  const { data: page } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
   const { data: space } = useSpaceQuery(spaceSlug);
   const [currentUser] = useAtom(currentUserAtom);
   const [renderItems, setRenderItems] = useState<MentionSuggestionItem[]>([]);
   const { t } = useTranslation();
-  const [data, setData] = useAtom(treeDataAtom);
+  // Setter-only: the tree value is read only imperatively inside createPage
+  // (via `store` below), never at render, so useSetAtom avoids re-rendering the
+  // mention popup on any tree event.
+  const setData = useSetAtom(treeDataAtom);
+  const store = useStore();
   const createPageMutation = useCreatePageMutation();
   const emit = useQueryEmit();
   const isInCommentContext = props.isInCommentContext ?? false;
@@ -272,9 +276,11 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
         children: [],
       };
 
-      const lastIndex = data.length;
+      // Read the live tree imperatively at call time.
+      const currentTree = store.get(treeDataAtom);
+      const lastIndex = currentTree.length;
 
-      setData(treeModel.insert(data, parentId, newNode, lastIndex));
+      setData(treeModel.insert(currentTree, parentId, newNode, lastIndex));
 
       props.command({
         id: uuid7(),

apps/client/src/features/editor/components/mention/mention-view.tsx

@@ -2,7 +2,7 @@ import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
 import { ActionIcon, Anchor, Text } from "@mantine/core";
 import { IconFileDescription } from "@tabler/icons-react";
 import { Link, useLocation, useNavigate, useParams } from "react-router-dom";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { useSharePageQuery } from "@/features/share/queries/share-query.ts";
 import {
   buildPageUrl,
@@ -36,7 +36,7 @@ export function MentionContent({ attrs }: { attrs: MentionAttrs }) {
     data: page,
     isLoading,
     isError,
-  } = usePageQuery({ pageId: isPageMention && !isShareRoute ? slugId : null });
+  } = usePageMetaQuery({ pageId: isPageMention && !isShareRoute ? slugId : null });
 
   const { data: sharedPage } = useSharePageQuery({
     pageId: isPageMention && isShareRoute ? slugId : undefined,

apps/client/src/features/editor/components/pdf/pdf-menu.tsx

@@ -25,6 +25,13 @@ export function PdfMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes unless a pdf node is active. The menu
+      // only shows for an active pdf node (shouldShow), so the null state while
+      // inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("pdf")) {
+        return null;
+      }
+
       const pdfAttrs = ctx.editor.getAttributes("pdf");
 
       return {

apps/client/src/features/editor/components/subpages/subpages-menu.tsx

@@ -70,7 +70,14 @@ export const SubpagesMenu = React.memo(
     // toggle without re-rendering on every keystroke.
     const isRecursive = useEditorState({
       editor,
-      selector: (ctx) => ctx.editor?.getAttributes("subpages")?.recursive ?? false,
+      // #343 PART 1: skip getAttributes unless a subpages node is active. The
+      // menu only shows for an active subpages node (shouldShow), so the value
+      // is only read then; getAttributes on an inactive node returns the default
+      // (recursive === false) anyway, so this is behavior-preserving.
+      selector: (ctx) =>
+        ctx.editor?.isActive("subpages")
+          ? (ctx.editor.getAttributes("subpages")?.recursive ?? false)
+          : false,
     });
 
     return (

apps/client/src/features/editor/components/table-of-contents/table-of-contents.tsx

@@ -4,6 +4,7 @@ import React, { FC, useEffect, useRef, useState } from "react";
 import classes from "./table-of-contents.module.css";
 import clsx from "clsx";
 import { Box, Text, Title } from "@mantine/core";
+import { useDebouncedCallback } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
 
 type TableOfContentsProps = {
@@ -79,13 +80,21 @@ export const TableOfContents: FC<TableOfContentsProps> = (props) => {
     setHeadingDOMNodes(result.nodes);
   };
 
+  // Debounce the update-driven rescan: `$nodes("heading")` scans every heading
+  // in the document, and it previously ran on EVERY keystroke while the TOC
+  // panel was open. The panel is derived UI, so recomputing ~300ms after typing
+  // settles keeps it correct without doing an all-headings scan per keystroke
+  // (#343, PART 7). `useDebouncedCallback` returns a stable reference and always
+  // invokes the latest `handleUpdate`.
+  const debouncedHandleUpdate = useDebouncedCallback(handleUpdate, 300);
+
   useEffect(() => {
-    props.editor?.on("update", handleUpdate);
+    props.editor?.on("update", debouncedHandleUpdate);
 
     return () => {
-      props.editor?.off("update", handleUpdate);
+      props.editor?.off("update", debouncedHandleUpdate);
     };
-  }, [props.editor]);
+  }, [props.editor, debouncedHandleUpdate]);
 
   useEffect(
     () => {

apps/client/src/features/editor/components/video/video-menu.tsx

@@ -31,6 +31,13 @@ export function VideoMenu({ editor }: EditorMenuProps) {
         return null;
       }
 
+      // #343 PART 1: skip getAttributes + alignment isActive() probes unless a
+      // video is active. The menu only shows for an active video (shouldShow),
+      // so the null state while inactive is never rendered — behavior unchanged.
+      if (!ctx.editor.isActive("video")) {
+        return null;
+      }
+
       const videoAttrs = ctx.editor.getAttributes("video");
 
       return {

apps/client/src/features/editor/extensions/extensions.ts

@@ -81,8 +81,8 @@ import {
   createResizeHandle,
   buildResizeClasses,
 } from "@/features/editor/components/common/node-resize-handles.ts";
-import MathInlineView from "@/features/editor/components/math/math-inline.tsx";
-import MathBlockView from "@/features/editor/components/math/math-block.tsx";
+import MathInlineView from "@/features/editor/components/math/math-inline-lazy.tsx";
+import MathBlockView from "@/features/editor/components/math/math-block-lazy.tsx";
 import ImageView from "@/features/editor/components/image/image-view.tsx";
 import CalloutView from "@/features/editor/components/callout/callout-view.tsx";
 import StatusView from "@/features/editor/components/status/status-view.tsx";
@@ -90,7 +90,7 @@ import VideoView from "@/features/editor/components/video/video-view.tsx";
 import AudioView from "@/features/editor/components/audio/audio-view.tsx";
 import AttachmentView from "@/features/editor/components/attachment/attachment-view.tsx";
 import CodeBlockView from "@/features/editor/components/code-block/code-block-view.tsx";
-import DrawioView from "../components/drawio/drawio-view";
+import DrawioView from "../components/drawio/drawio-view-lazy.tsx";
 import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-view-lazy.tsx";
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import HtmlEmbedView from "@/features/editor/components/html-embed/html-embed-view.tsx";

apps/client/src/features/editor/extensions/slash-command.ts

@@ -6,6 +6,23 @@ import getSuggestionItems from '@/features/editor/components/slash-menu/menu-ite
 
 export const slashMenuPluginKey = new PluginKey('slash-command');
 
+// getSuggestionItems fuzzy-matches EVERY command against the query (plus its
+// wrong-keyboard-layout remaps) and, while the slash menu is open, is invoked
+// TWICE per keystroke: once by the synchronous `allow` gate below and once by
+// the popup's `items` builder. A synchronous gating predicate can't be
+// debounced without breaking the suggestion decoration/activation, so instead we
+// memoize the LAST query's result: the two same-query calls in one keystroke
+// build the list only once, and the cache invalidates the moment the query
+// changes — so there is no stale-state risk (#343, PART 7).
+let lastQuery: string | null = null;
+let lastResult: ReturnType<typeof getSuggestionItems> | null = null;
+function suggestionItemsForQuery(query: string) {
+  if (query === lastQuery && lastResult) return lastResult;
+  lastQuery = query;
+  lastResult = getSuggestionItems({ query });
+  return lastResult;
+}
+
 // @ts-ignore
 const Command = Extension.create({
   name: 'slash-command',
@@ -38,7 +55,7 @@ const Command = Extension.create({
           // non-matching queries while keeping multi-word matches (e.g.
           // "/Heading 1") working.
           const query = state.doc.textBetween(range.from + 1, range.to);
-          const groups = getSuggestionItems({ query });
+          const groups = suggestionItemsForQuery(query);
           const hasMatches = Object.values(groups).some(
             (items) => items.length > 0,
           );
@@ -61,7 +78,9 @@ const Command = Extension.create({
 
 const SlashCommand = Command.configure({
   suggestion: {
-    items: getSuggestionItems,
+    // Share the per-query memo with `allow` so the pair of same-query calls in a
+    // single keystroke rebuilds the list once (#343, PART 7).
+    items: ({ query }: { query: string }) => suggestionItemsForQuery(query),
     render: renderItems,
   },
 });

apps/client/src/features/editor/gitmost/gitmost-global-bridge.tsx

@@ -1,8 +1,17 @@
 import { useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
 import { getDefaultStore } from "jotai";
-import { WebSocketStatus } from "@hocuspocus/provider";
-import { Editor } from "@tiptap/core";
+
+// Literal value of WebSocketStatus.Connected from @hocuspocus/provider. Inlined
+// so this always-mounted global bridge does not statically import
+// @hocuspocus/provider — that import pulls Yjs (and, through a shared chunk, the
+// whole TipTap engine) into the eager startup graph. yjsConnectionStatusAtom
+// already stores these raw status strings.
+const YJS_STATUS_CONNECTED = "connected";
+// Type-only: importing Editor as a type keeps @tiptap/core (the whole editor
+// engine) out of the eager global-shell graph — the bridge only uses it for
+// annotations/casts, never as a runtime value.
+import type { Editor } from "@tiptap/core";
 import {
   pageEditorAtom,
   yjsConnectionStatusAtom,
@@ -16,16 +25,19 @@ import {
   getSidebarPages,
 } from "@/features/page/services/page-service.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
-import {
+// Types are erased at build time, so importing them does not pull the module's
+// runtime (which drags in @tiptap + the editor-ext barrel). The actual recording
+// helpers are dynamically imported at call time inside createPageWithRecording,
+// keeping the editor engine out of the eager global-shell startup graph — the
+// bridge is mounted for every authenticated user but recording is a rare,
+// native-host-driven action.
+import type {
   GitmostBridge,
   GitmostCreatePagePayload,
   GitmostCreatePageResult,
   GitmostListPagesPayload,
   GitmostListPagesResult,
   GitmostListSpacesResult,
-  gitmostDecodePayloadToFile,
-  gitmostInsertTranscriptIntoEditor,
-  gitmostUploadFileToEditor,
 } from "@/features/editor/gitmost/gitmost-recording.ts";
 
 // How long to wait for a freshly-navigated page's editor to mount, become
@@ -58,7 +70,7 @@ function gitmostWaitForEditor(
         !editor.isDestroyed &&
         editor.isEditable &&
         editorPageId === pageId &&
-        yjsStatus === WebSocketStatus.Connected;
+        yjsStatus === YJS_STATUS_CONNECTED;
       if (ready) {
         resolve(editor);
         return;
@@ -172,6 +184,15 @@ export default function GitmostGlobalBridge() {
           };
         }
 
+        // Load the recording helpers on demand (see the import note above). This
+        // is the only place they are needed, so the @tiptap/editor-ext code they
+        // pull in stays out of the eager startup graph.
+        const {
+          gitmostDecodePayloadToFile,
+          gitmostUploadFileToEditor,
+          gitmostInsertTranscriptIntoEditor,
+        } = await import("@/features/editor/gitmost/gitmost-recording.ts");
+
         // Validate/decode the recording BEFORE creating the page so a bad
         // payload never leaves an empty junk page behind. Per the createPage
         // error contract, any decode failure collapses to "insert-failed" (the

apps/client/src/features/editor/hooks/use-page-content-cache.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { MutableRefObject } from "react";
+import type { Editor } from "@tiptap/react";
+
+// Mock the app entry so importing the hook doesn't boot the whole app; the hook
+// only needs queryClient's cache read/write, which we stub here. Declared via
+// vi.hoisted so the spies exist before the hoisted vi.mock factory runs.
+const { getQueryData, setQueryData } = vi.hoisted(() => ({
+  getQueryData: vi.fn(() => undefined as unknown),
+  setQueryData: vi.fn(),
+}));
+vi.mock("@/main.tsx", () => ({
+  queryClient: { getQueryData, setQueryData },
+}));
+
+import { usePageContentCache } from "./use-page-content-cache";
+
+const SNAPSHOT = { type: "doc", content: [] };
+
+function makeFakeEditor(overrides: Partial<Editor> = {}): Editor {
+  return {
+    isEmpty: false,
+    isDestroyed: false,
+    getJSON: vi.fn(() => SNAPSHOT),
+    ...overrides,
+  } as unknown as Editor;
+}
+
+describe("usePageContentCache (#343 PART 3) — getJSON off the keystroke path", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    // A cached page exists so the write path runs.
+    getQueryData.mockReturnValue({ id: "p1", content: {} });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("onUpdate (calling the debounced fn) does NOT call getJSON synchronously", () => {
+    const editor = makeFakeEditor();
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    // Simulate a keystroke's onUpdate -> only schedules the debounce.
+    act(() => {
+      result.current();
+      result.current();
+      result.current();
+    });
+
+    // The whole-doc serialization must NOT have happened yet.
+    expect(editor.getJSON).not.toHaveBeenCalled();
+    expect(setQueryData).not.toHaveBeenCalled();
+
+    // Once the debounce window elapses, getJSON runs exactly once (not per call).
+    act(() => vi.advanceTimersByTime(3000));
+    expect(editor.getJSON).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledWith(["pages", "slug-1"], {
+      id: "p1",
+      content: SNAPSHOT,
+    });
+  });
+
+  it("flushes the pending snapshot on unmount so the last edit isn't lost", () => {
+    const editor = makeFakeEditor();
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result, unmount } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    act(() => result.current());
+    expect(editor.getJSON).not.toHaveBeenCalled();
+
+    // Navigation/unmount must flush (not drop) the pending write.
+    act(() => unmount());
+    expect(editor.getJSON).toHaveBeenCalledTimes(1);
+    expect(setQueryData).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips the write when the editor is destroyed (flush racing teardown)", () => {
+    const editor = makeFakeEditor({ isDestroyed: true });
+    const editorRef = { current: editor } as MutableRefObject<Editor | null>;
+
+    const { result } = renderHook(() =>
+      usePageContentCache(editorRef, "slug-1", 3000),
+    );
+
+    act(() => result.current());
+    act(() => vi.advanceTimersByTime(3000));
+
+    expect(editor.getJSON).not.toHaveBeenCalled();
+    expect(setQueryData).not.toHaveBeenCalled();
+  });
+});

apps/client/src/features/editor/hooks/use-page-content-cache.ts

@@ -0,0 +1,50 @@
+import type { MutableRefObject } from "react";
+import { useDebouncedCallback } from "@mantine/hooks";
+import type { Editor } from "@tiptap/react";
+import { queryClient } from "@/main.tsx";
+import { IPage } from "@/features/page/types/page.types.ts";
+
+/**
+ * Off-keystroke local page-cache updater (issue #343, PART 3).
+ *
+ * The editor's `onUpdate` fires on every keystroke — and, under collaboration,
+ * on every REMOTE keystroke too. Serializing the WHOLE document with
+ * `editor.getJSON()` on that hot path is expensive, and the previous 3s debounce
+ * only guarded the cache WRITE, not the serialization: `getJSON()` still ran per
+ * keystroke.
+ *
+ * This hook moves the serialization INSIDE the debounced callback, so the
+ * full-doc traversal happens at most once per `delay`, not per keystroke. Call
+ * the returned function from `onUpdate` (it only schedules the debounce); the
+ * `getJSON()` snapshot is taken when the debounce fires.
+ *
+ * On unmount/navigation the pending snapshot is FLUSHED (via `flushOnUnmount`)
+ * so the last edits within the debounce window aren't lost from the local cache.
+ * The source of truth is collab/Yjs, but the cache must not go stale.
+ *
+ * IMPORTANT: call this hook BEFORE `useEditor`. React runs effect cleanups in
+ * declaration order on unmount, so the debounce's flush cleanup must be declared
+ * before `useEditor`'s teardown to run while the editor is still alive; the
+ * `isDestroyed` guard keeps a flush that still races teardown safe (it skips).
+ */
+export function usePageContentCache(
+  editorRef: MutableRefObject<Editor | null>,
+  slugId: string | undefined,
+  delay = 3000,
+) {
+  return useDebouncedCallback(
+    () => {
+      const e = editorRef.current;
+      if (!e || e.isDestroyed || e.isEmpty) return;
+      const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
+      if (pageData) {
+        // getJSON() (full-doc serialization) runs HERE, off the keystroke path.
+        queryClient.setQueryData(["pages", slugId], {
+          ...pageData,
+          content: e.getJSON(),
+        });
+      }
+    },
+    { delay, flushOnUnmount: true },
+  );
+}

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

@@ -59,10 +59,10 @@ import {
   handlePaste,
 } from "@/features/editor/components/common/editor-paste-handler.tsx";
 import ExcalidrawMenu from "./components/excalidraw/excalidraw-menu-lazy";
-import DrawioMenu from "./components/drawio/drawio-menu";
+import DrawioMenu from "./components/drawio/drawio-menu-lazy";
 import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import SearchAndReplaceDialog from "@/features/editor/components/search-and-replace/search-and-replace-dialog.tsx";
-import { useDebouncedCallback, useDocumentVisibility } from "@mantine/hooks";
+import { useDocumentVisibility } from "@mantine/hooks";
 import { useIdle } from "@/hooks/use-idle.ts";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
@@ -79,6 +79,7 @@ import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { jwtDecode } from "jwt-decode";
 import { searchSpotlight } from "@/features/search/constants.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
+import { usePageContentCache } from "./hooks/use-page-content-cache";
 import { useScrollRestoreOnSwap } from "./hooks/use-scroll-position";
 import { useSwapHeightReservation } from "./hooks/use-swap-height-reservation";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
@@ -272,8 +273,13 @@ export default function PageEditor({
     }
   }, [isIdle, documentState, providersReady, resetIdle]);
 
-  // Attach here, to make sure the connection gets properly established
-  providersRef.current?.remote.attach();
+  // Attach the remote provider once it's ready (and again after a pageId swap
+  // recreates it) to make sure the connection gets properly established. This
+  // used to run in the render body — a side effect during render (#343, PART 7).
+  // `attach()` is idempotent, so re-running it on these deps is safe.
+  useEffect(() => {
+    providersRef.current?.remote.attach();
+  }, [providersReady, pageId]);
 
   const extensions = useMemo(() => {
     if (!providersReady || !providersRef.current || !currentUser?.user) {
@@ -288,6 +294,12 @@ export default function PageEditor({
     ];
   }, [providersReady, currentUser?.user]);
 
+  // getJSON() serialization + cache write live in the hook, off the keystroke
+  // path, and flush on unmount so the last snapshot survives navigation (#343).
+  // MUST be declared before useEditor: React runs effect cleanups in declaration
+  // order on unmount, so the flush must run before the editor is torn down.
+  const debouncedUpdateContent = usePageContentCache(editorRef, slugId);
+
   const editor = useEditor(
     {
       extensions,
@@ -392,11 +404,11 @@ export default function PageEditor({
           }
         }
       },
-      onUpdate({ editor }) {
-        if (editor.isEmpty) return;
-        const editorJson = editor.getJSON();
-        //update local page cache to reduce flickers
-        debouncedUpdateContent(editorJson);
+      onUpdate() {
+        // Only schedule the debounce here — the whole-doc getJSON() serialization
+        // happens INSIDE the debounced callback (see usePageContentCache), so it
+        // no longer runs synchronously on every (local or remote) keystroke.
+        debouncedUpdateContent();
       },
     },
     [pageId, editable, extensions],
@@ -442,17 +454,6 @@ export default function PageEditor({
     };
   }, [editor, pageId, editorIsEditable]);
 
-  const debouncedUpdateContent = useDebouncedCallback((newContent: any) => {
-    const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-
-    if (pageData) {
-      queryClient.setQueryData(["pages", slugId], {
-        ...pageData,
-        content: newContent,
-      });
-    }
-  }, 3000);
-
   const handleActiveCommentEvent = (event) => {
     const { commentId, resolved } = event.detail;
 

apps/client/src/features/favorite/queries/favorite-query.ts

@@ -24,7 +24,6 @@ export function useFavoritesQuery(type?: FavoriteType, spaceId?: string) {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
-    refetchOnMount: true,
   });
 }
 
@@ -32,7 +31,6 @@ export function useFavoriteIds(type: FavoriteType, spaceId?: string): Set<string
   const { data } = useQuery({
     queryKey: ["favorite-ids", type, spaceId],
     queryFn: () => getFavoriteIds(type, spaceId),
-    refetchOnMount: true,
   });
 
   const items = data?.items;

apps/client/src/features/page-details/components/page-details-aside.tsx

@@ -12,7 +12,7 @@ import { useAtomValue } from "jotai";
 import { useParams } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { extractPageSlugId } from "@/lib";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import { useBacklinksCountQuery } from "@/features/page-details/queries/backlinks-query.ts";
 import { BacklinksModal } from "./backlinks-modal";
@@ -23,7 +23,7 @@ import { LabelsSection } from "@/features/label/components/labels-section.tsx";
 
 export function PageDetailsAside() {
   const { pageSlug } = useParams();
-  const { data: page } = usePageQuery({
+  const { data: page } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const pageEditor = useAtomValue(pageEditorAtom);

apps/client/src/features/page/components/breadcrumbs/breadcrumb-path-equal.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from "vitest";
+import { SpaceTreeNode } from "@/features/page/tree/types";
+
+// breadcrumb.tsx transitively imports @/main.tsx (via usePageMetaQuery ->
+// queryClient), whose module body calls ReactDOM.createRoot on a null root in
+// jsdom. Stub it so importing the pure helper under test doesn't run that
+// (breadcrumbPathEqual does not use queryClient, so a dummy is enough).
+vi.mock("@/main.tsx", () => ({ queryClient: {} }));
+
+import { breadcrumbPathEqual } from "./breadcrumb";
+
+// breadcrumbPathEqual is the ONLY point where a false-positive equality would
+// leave a stale/incorrect breadcrumb trail on screen: it decides whether the
+// selectAtom hands back the same reference (no re-render) for the ancestor chain.
+// Pin both directions — a too-loose equality goes stale on a rename; a too-tight
+// one loses the perf win.
+const node = (over: Partial<SpaceTreeNode>): SpaceTreeNode =>
+  ({ id: "a", slugId: "sa", name: "A", icon: "📄", ...over }) as SpaceTreeNode;
+
+describe("breadcrumbPathEqual", () => {
+  it("both null → true", () => {
+    expect(breadcrumbPathEqual(null, null)).toBe(true);
+  });
+
+  it("same reference → true", () => {
+    const p = [node({})];
+    expect(breadcrumbPathEqual(p, p)).toBe(true);
+  });
+
+  it("equal by id/slugId/name/icon (different arrays) → true", () => {
+    expect(breadcrumbPathEqual([node({})], [node({})])).toBe(true);
+  });
+
+  it("one side null → false", () => {
+    expect(breadcrumbPathEqual([node({})], null)).toBe(false);
+    expect(breadcrumbPathEqual(null, [node({})])).toBe(false);
+  });
+
+  it("different length → false", () => {
+    expect(
+      breadcrumbPathEqual([node({})], [node({}), node({ id: "b" })]),
+    ).toBe(false);
+  });
+
+  it.each(["name", "icon", "slugId", "id"] as const)(
+    "a changed %s → false (breadcrumb must re-render)",
+    (field) => {
+      expect(
+        breadcrumbPathEqual([node({})], [node({ [field]: "CHANGED" })]),
+      ).toBe(false);
+    },
+  );
+});

apps/client/src/features/page/components/breadcrumbs/breadcrumb.tsx

@@ -1,7 +1,9 @@
 import { useAtomValue } from "jotai";
+import { selectAtom } from "jotai/utils";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
-import React, { useCallback, useEffect, useState } from "react";
+import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { computeBreadcrumbState } from "./breadcrumb.utils";
+import { findBreadcrumbPath } from "@/features/page/tree/utils";
 import {
   Button,
   Anchor,
@@ -18,7 +20,7 @@ import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import {
-  usePageQuery,
+  usePageMetaQuery,
   usePageBreadcrumbsQuery,
 } from "@/features/page/queries/page-query.ts";
 import { extractPageSlugId } from "@/lib";
@@ -32,39 +34,84 @@ function getTitle(name: string, icon: string) {
   return name;
 }
 
+/**
+ * Equality over a breadcrumb chain by the only fields the breadcrumb renders
+ * (id, slugId, name, icon). Lets the selectAtom below hand back the SAME
+ * reference when an unrelated tree mutation leaves THIS page's ancestor chain
+ * visually unchanged, so the breadcrumb no longer re-renders on every tree
+ * event (it previously subscribed to the whole treeDataAtom).
+ */
+export function breadcrumbPathEqual(
+  a: SpaceTreeNode[] | null,
+  b: SpaceTreeNode[] | null,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (
+      a[i].id !== b[i].id ||
+      a[i].slugId !== b[i].slugId ||
+      a[i].name !== b[i].name ||
+      a[i].icon !== b[i].icon
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 export default function Breadcrumb() {
   const { t } = useTranslation();
-  const treeData = useAtomValue(treeDataAtom);
   const [breadcrumbNodes, setBreadcrumbNodes] = useState<
     SpaceTreeNode[] | null
   >(null);
   const { pageSlug, spaceSlug } = useParams();
-  const { data: currentPage } = usePageQuery({
+  const { data: currentPage } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
+  const currentPageId = currentPage?.id;
   // The page's own ancestor chain, fetched independently of the lazily-built
   // sidebar tree so a deep page doesn't render a blank breadcrumb for seconds
   // while the tree backfills (#218).
-  const { data: ancestors } = usePageBreadcrumbsQuery(currentPage?.id);
+  const { data: ancestors } = usePageBreadcrumbsQuery(currentPageId);
   const isMobile = useMediaQuery("(max-width: 48em)");
 
+  // Narrowed subscription: instead of subscribing to the whole treeDataAtom and
+  // recomputing on every tree event, derive ONLY the current page's ancestor
+  // chain. The custom equality returns the previous reference when that chain is
+  // visually unchanged, so an unrelated tree mutation no longer re-renders this
+  // component. Mirrors computeBreadcrumbState's tree-hit branch
+  // (findBreadcrumbPath); the tree-miss/ancestors fallback is applied below.
+  const treePathAtom = useMemo(
+    () =>
+      selectAtom(
+        treeDataAtom,
+        (tree): SpaceTreeNode[] | null =>
+          currentPageId ? findBreadcrumbPath(tree, currentPageId) : null,
+        breadcrumbPathEqual,
+      ),
+    [currentPageId],
+  );
+  const treePath = useAtomValue(treePathAtom);
+
   useEffect(() => {
     if (!currentPage) return;
 
     // Selection/mapping + stale-clearing live in a pure, unit-tested helper
-    // (#218). It resolves the correct chain when possible and, on a transient
-    // miss, clears a chain left over from a previously-viewed page instead of
-    // showing the wrong trail — while keeping a chain already resolved for THIS
-    // page to avoid a blank flash.
+    // (#218). The tree-hit chain (treePath) always wins when present; otherwise
+    // fall back to the page's own ancestors and the stale-clearing logic — this
+    // reproduces computeBreadcrumbState(fullTree, ancestors, …) exactly, since
+    // its tree-hit branch is precisely findBreadcrumbPath(fullTree, pageId).
     setBreadcrumbNodes((previous) =>
+      treePath ??
       computeBreadcrumbState(
-        treeData,
+        null,
         ancestors as IPage[] | undefined,
         currentPage.id,
         previous,
       ),
     );
-  }, [currentPage?.id, treeData, ancestors]);
+  }, [currentPage?.id, treePath, ancestors]);
 
   const HiddenNodesTooltipContent = () =>
     breadcrumbNodes?.slice(1, -1).map((node) => (

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

@@ -24,7 +24,7 @@ import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
 import { useDisclosure, useHotkeys } from "@mantine/hooks";
 import { useClipboard } from "@/hooks/use-clipboard";
 import { useParams } from "react-router-dom";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import {
   useToggleTemporaryMutation,
   syncTemporaryExpiresInCache,
@@ -67,7 +67,7 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
   const commentsTriggerProps = useAsideTriggerProps("comments");
   const tocTriggerProps = useAsideTriggerProps("toc");
   const { pageSlug } = useParams();
-  const { data: page } = usePageQuery({
+  const { data: page } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const isDeleted = !!page?.deletedAt;
@@ -146,7 +146,7 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
   const [, setHistoryModalOpen] = useAtom(historyAtoms);
   const clipboard = useClipboard({ timeout: 500 });
   const { pageSlug, spaceSlug } = useParams();
-  const { data: page, isLoading } = usePageQuery({
+  const { data: page, isLoading } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
   const { handleDelete } = useTreeMutation(page?.spaceId ?? "");

apps/client/src/features/page/components/temporary-note-banner.tsx

@@ -10,7 +10,7 @@ import { IconClockHour4, IconTrash } from "@tabler/icons-react";
 import { useState } from "react";
 import { Trans, useTranslation } from "react-i18next";
 import { useTimeAgo } from "@/hooks/use-time-ago.tsx";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
 import {
   useToggleTemporaryMutation,
@@ -35,7 +35,7 @@ type TemporaryNoteBannerProps = {
  */
 export function TemporaryNoteBanner({ slugId }: TemporaryNoteBannerProps) {
   const { t } = useTranslation();
-  const { data: page } = usePageQuery({ pageId: slugId });
+  const { data: page } = usePageMetaQuery({ pageId: slugId });
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
   const spaceAbility = useSpaceAbility(space?.membership?.permissions);
   const expiresTimeAgo = useTimeAgo(page?.temporaryExpiresAt);

apps/client/src/features/page/queries/invalidate-on-update-page.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import type { IPage } from "@/features/page/types/page.types";
+
+// A fresh QueryClient stands in for the app singleton (importing the real
+// @/main.tsx would run ReactDOM.createRoot, which has no DOM root in jsdom). The
+// factory constructs it (QueryClient can't be referenced in vi.hoisted — that
+// runs before imports resolve); we import the SAME mocked instance back to seed
+// and assert on it.
+vi.mock("@/main.tsx", async () => {
+  const { QueryClient } = await import("@tanstack/react-query");
+  return { queryClient: new QueryClient() };
+});
+
+import { queryClient as h_qc } from "@/main.tsx";
+import { invalidateOnUpdatePage } from "./page-query";
+
+const h = { qc: h_qc };
+
+// invalidateOnUpdatePage is the field-only (title/icon) tree path: instead of a
+// blanket invalidate it patches the affected node IN PLACE in every cached embed
+// subtree. The undefined-guard is LOAD-BEARING: a title-only socket event carries
+// icon:undefined, and without the guard `{...p, icon: undefined}` would WIPE the
+// icon in every cached subtree.
+const page = (over: Partial<IPage>): IPage =>
+  ({ id: "p1", title: "Old", icon: "📄", spaceId: "s1" }) as IPage &
+    typeof over as IPage;
+
+describe("invalidateOnUpdatePage — pointwise embed-cache patch", () => {
+  beforeEach(() => {
+    h.qc.clear();
+  });
+
+  it("title-only event updates title but PRESERVES the icon (undefined-guard)", () => {
+    const key = ["page-tree", "parent-1"];
+    h.qc.setQueryData<IPage[]>(key, [
+      { id: "p1", title: "Old", icon: "📄", spaceId: "s1" } as IPage,
+      { id: "p2", title: "Other", icon: "📁", spaceId: "s1" } as IPage,
+    ]);
+
+    // icon passed as undefined (a title-only update)
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      "New Title",
+      undefined as unknown as string,
+    );
+
+    const patched = h.qc.getQueryData<IPage[]>(key)!;
+    const p1 = patched.find((p) => p.id === "p1")!;
+    const p2 = patched.find((p) => p.id === "p2")!;
+    expect(p1.title).toBe("New Title");
+    expect(p1.icon).toBe("📄"); // preserved, not wiped
+    // Sibling node untouched.
+    expect(p2.title).toBe("Other");
+    expect(p2.icon).toBe("📁");
+  });
+
+  it("icon-only event updates icon but preserves the title", () => {
+    const key = ["page-tree", "parent-1"];
+    h.qc.setQueryData<IPage[]>(key, [
+      { id: "p1", title: "Keep", icon: "📄", spaceId: "s1" } as IPage,
+    ]);
+
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      undefined as unknown as string,
+      "🚀",
+    );
+
+    const p1 = h.qc.getQueryData<IPage[]>(key)!.find((p) => p.id === "p1")!;
+    expect(p1.icon).toBe("🚀");
+    expect(p1.title).toBe("Keep");
+  });
+
+  // The sidebar-pages cache (InfiniteData) is patched on the same event. It must
+  // carry the SAME undefined-guard as the embed path above — otherwise a
+  // title-only event's icon:undefined would wipe the sidebar entry's icon.
+  const sidebarKey = ["sidebar-pages", { pageId: "parent-1", spaceId: "s1" }];
+  const seedSidebar = () =>
+    h.qc.setQueryData(sidebarKey, {
+      pageParams: [undefined],
+      pages: [
+        {
+          items: [
+            { id: "p1", title: "Old", icon: "📄", spaceId: "s1" } as IPage,
+            { id: "p2", title: "Other", icon: "📁", spaceId: "s1" } as IPage,
+          ],
+        },
+      ],
+    });
+  const sidebarItem = (id: string) => {
+    const data = h.qc.getQueryData(sidebarKey) as {
+      pages: { items: IPage[] }[];
+    };
+    return data.pages[0].items.find((p) => p.id === id)!;
+  };
+
+  it("sidebar cache: title-only event updates title but PRESERVES the icon", () => {
+    seedSidebar();
+
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      "New Title",
+      undefined as unknown as string,
+    );
+
+    const p1 = sidebarItem("p1");
+    expect(p1.title).toBe("New Title");
+    expect(p1.icon).toBe("📄"); // preserved, not wiped
+    // Sibling untouched.
+    const p2 = sidebarItem("p2");
+    expect(p2.title).toBe("Other");
+    expect(p2.icon).toBe("📁");
+  });
+
+  it("sidebar cache: icon-only event updates icon but PRESERVES the title", () => {
+    seedSidebar();
+
+    invalidateOnUpdatePage(
+      "s1",
+      "parent-1",
+      "p1",
+      undefined as unknown as string,
+      "🚀",
+    );
+
+    const p1 = sidebarItem("p1");
+    expect(p1.icon).toBe("🚀");
+    expect(p1.title).toBe("Old"); // preserved, not wiped
+  });
+
+  it("does not touch a subtree that lacks the updated node", () => {
+    const otherKey = ["page-tree", "unrelated"];
+    const before = [
+      { id: "x1", title: "X", icon: "❌", spaceId: "s1" } as IPage,
+    ];
+    h.qc.setQueryData<IPage[]>(otherKey, before);
+
+    invalidateOnUpdatePage("s1", "parent-1", "p1", "New", "🚀");
+
+    // Same reference back — the subtree without p1 is left as-is.
+    expect(h.qc.getQueryData<IPage[]>(otherKey)).toBe(before);
+  });
+});

apps/client/src/features/page/queries/page-query.ts

@@ -51,6 +51,10 @@ export function usePageQuery(
     queryFn: () => getPageById(pageInput),
     enabled: !!pageInput.pageId,
     staleTime: 5 * 60 * 1000,
+    // Keep the previously-loaded page visible while navigating to a new one
+    // instead of flashing a blank/skeleton frame (the new page's content
+    // streams in when ready). isLoading stays true only for the very first load.
+    placeholderData: keepPreviousData,
   });
 
   useEffect(() => {
@@ -66,6 +70,61 @@ export function usePageQuery(
   return query;
 }
 
+/**
+ * A page view that omits the large, frequently-changing `content` field. Every
+ * other field is preserved, so consumers that read only metadata (title, icon,
+ * permissions, id, creator, timestamps, …) keep working unchanged.
+ */
+export type IPageMeta = Omit<IPage, "content">;
+
+function selectPageMeta(page: IPage): IPageMeta {
+  // Drop `content`; react-query's structural sharing (replaceEqualDeep) then
+  // returns the SAME reference whenever the remaining fields are unchanged, so a
+  // pure content churn (typing / debouncedUpdateContent, collab `page.updated`)
+  // no longer changes this slice's identity and its ~13 subscribers don't
+  // re-render on every keystroke wave.
+  const { content: _content, ...meta } = page;
+  return meta as IPageMeta;
+}
+
+/**
+ * Metadata-only variant of {@link usePageQuery}. Shares the SAME query cache
+ * entry (`["pages", pageId]`, full object incl. content), but this hook returns
+ * a stable content-less slice so peripheral subscribers stop re-rendering on
+ * every content update. Use it anywhere the full `content` is not read.
+ */
+export function usePageMetaQuery(
+  pageInput: Partial<IPageInput>,
+): UseQueryResult<IPageMeta, Error> {
+  const query = useQuery({
+    queryKey: ["pages", pageInput.pageId],
+    queryFn: () => getPageById(pageInput),
+    enabled: !!pageInput.pageId,
+    staleTime: 5 * 60 * 1000,
+    select: selectPageMeta,
+    // Match usePageQuery: keep the previous page's metadata visible while
+    // navigating so the periphery (header, breadcrumb, …) doesn't flash blank.
+    placeholderData: keepPreviousData,
+  });
+
+  // Mirror usePageQuery's cross-key alias write so a page fetched by one
+  // identifier is also cached under the other. The cache stores the FULL page
+  // (select only narrows what THIS hook returns), so read the full object back
+  // from the cache and alias THAT — never the content-less slice.
+  useEffect(() => {
+    if (!query.data) return;
+    const full = queryClient.getQueryData<IPage>(["pages", pageInput.pageId]);
+    if (!full) return;
+    if (isValidUuid(pageInput.pageId)) {
+      queryClient.setQueryData(["pages", full.slugId], full);
+    } else {
+      queryClient.setQueryData(["pages", full.id], full);
+    }
+  }, [query.data]);
+
+  return query;
+}
+
 export function useCreatePageMutation() {
   const { t } = useTranslation();
   return useMutation<IPage, Error, Partial<IPageInput>>({
@@ -351,6 +410,12 @@ export function useRecentChangesQuery(spaceId?: string) {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
+    // KEEP refetchOnMount:true (against the global default false): recent-changes
+    // IS invalidated on page create/update/move/delete, but invalidateQueries only
+    // marks an UNMOUNTED query stale — it doesn't refetch it. The widget isn't
+    // always mounted, so an event that lands while it's unmounted leaves it stale,
+    // and the global refetchOnMount:false would not re-fetch on remount. The mount
+    // refetch closes that gap.
     refetchOnMount: true,
   });
 }
@@ -367,6 +432,9 @@ export function useCreatedByQuery(params?: {
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) =>
       lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
+    // KEEP refetchOnMount:true: the "created-by" key is never invalidated (no
+    // socket/mutation path), so the mount refetch is its ONLY freshness mechanism
+    // — without it the list shows stale cache on navigation.
     refetchOnMount: true,
   });
 }
@@ -380,8 +448,14 @@ export function useDeletedPagesQuery(
     queryFn: () => getDeletedPages(spaceId, params),
     enabled: !!spaceId,
     placeholderData: keepPreviousData,
-    refetchOnMount: true,
     staleTime: 0,
+    // KEEP refetchOnMount:true: ["trash-list"] IS invalidated by the
+    // move-to-trash / delete / restore mutations, but invalidateQueries only marks
+    // an unmounted query stale — it doesn't refetch it. The trash panel isn't
+    // usually mounted when a page is trashed, so on opening it the global
+    // refetchOnMount:false would show a stale list; the mount refetch closes that.
+    // (Do NOT remove the three trash-list invalidations — they are not dead code.)
+    refetchOnMount: true,
   });
 }
 
@@ -516,7 +590,35 @@ export function invalidateOnUpdatePage(
   title: string,
   icon: string,
 ) {
-  invalidatePageTree();
+  // Scoped page-tree refresh (was a blanket `invalidatePageTree()`): this is the
+  // FIELD-only update path (title/icon — no structural change), and the sidebar
+  // tree is already updated pointwise (applyUpdateOne / optimistic setData) plus
+  // via the sidebar-pages cache below. Invalidating ALL ["page-tree"] queries
+  // here refetched every open recursive subpages-embed block on each
+  // rename/icon-change — pure duplicate work. Instead patch just the affected
+  // node IN PLACE in every cached embed subtree: same visible result, no network
+  // churn, no full embed-tree rebuild. Structural events (create/move/delete)
+  // keep the blanket invalidate in their own helpers.
+  const pageTreeMatches = queryClient.getQueriesData<IPage[]>({
+    queryKey: ["page-tree"],
+  });
+  pageTreeMatches.forEach(([key, items]) => {
+    if (!items || !items.some((p) => p.id === id)) return;
+    queryClient.setQueryData<IPage[]>(key, (old) =>
+      old?.map((p) =>
+        p.id === id
+          ? {
+              ...p,
+              // Guard undefined so a title-only event can't wipe the icon (and
+              // vice versa) in the embed cache.
+              ...(title !== undefined ? { title } : {}),
+              ...(icon !== undefined ? { icon } : {}),
+            }
+          : p,
+      ),
+    );
+  });
+
   let queryKey: QueryKey = null;
   if (parentPageId === null) {
     queryKey = ["root-sidebar-pages", spaceId];
@@ -534,7 +636,14 @@ export function invalidateOnUpdatePage(
           ...page,
           items: page.items.map((sidebarPage: IPage) =>
             sidebarPage.id === id
-              ? { ...sidebarPage, title: title, icon: icon }
+              ? {
+                  ...sidebarPage,
+                  // Guard undefined so a title-only event can't wipe the icon
+                  // (and vice versa) in the sidebar-pages cache — mirrors the
+                  // embed-cache patch above.
+                  ...(title !== undefined ? { title } : {}),
+                  ...(icon !== undefined ? { icon } : {}),
+                }
               : sidebarPage,
           ),
         })),

apps/client/src/features/page/trash/components/deleted-page-banner.tsx

@@ -7,7 +7,7 @@ import { useRestorePageModal } from "@/features/page/hooks/use-restore-page-moda
 import { useDeletePageModal } from "@/features/page/hooks/use-delete-page-modal.tsx";
 import {
   useDeletePageMutation,
-  usePageQuery,
+  usePageMetaQuery,
   useRestorePageMutation,
 } from "@/features/page/queries/page-query.ts";
 import { getSpaceUrl } from "@/lib/config.ts";
@@ -25,7 +25,7 @@ type DeletedPageBannerProps = {
 export function DeletedPageBanner({ slugId }: DeletedPageBannerProps) {
   const { t } = useTranslation();
   const navigate = useNavigate();
-  const { data: page } = usePageQuery({ pageId: slugId });
+  const { data: page } = usePageMetaQuery({ pageId: slugId });
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
   const spaceAbility = useSpaceAbility(space?.membership?.permissions);
   const deletedTimeAgo = useTimeAgo(page?.deletedAt);

apps/client/src/features/page/tree/components/space-tree-node-menu.tsx

@@ -1,4 +1,4 @@
-import { useAtom } from "jotai";
+import { useSetAtom, useStore } from "jotai";
 import { useTranslation } from "react-i18next";
 import { useParams } from "react-router-dom";
 import { ActionIcon, Menu, rem } from "@mantine/core";
@@ -52,7 +52,11 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
   const clipboard = useClipboard({ timeout: 500 });
   const { spaceSlug } = useParams();
   const { handleDelete } = useTreeMutation(node.spaceId);
-  const [data, setData] = useAtom(treeDataAtom);
+  // Setter-only: the tree value is read only imperatively inside the duplicate
+  // handler (via `store` below), never at render, so useSetAtom avoids
+  // re-rendering every row's NodeMenu on any tree event.
+  const setData = useSetAtom(treeDataAtom);
+  const store = useStore();
   const emit = useQueryEmit();
   const [exportOpened, { open: openExportModal, close: closeExportModal }] =
     useDisclosure(false);
@@ -125,8 +129,8 @@ export function NodeMenu({ node, canEdit }: NodeMenuProps) {
     try {
       const duplicatedPage = await duplicatePage({ pageId: node.id });
 
-      // figure out parent + insertion index
-      const siblings = treeModel.siblingsOf(data, node.id);
+      // figure out parent + insertion index (read the live tree imperatively)
+      const siblings = treeModel.siblingsOf(store.get(treeDataAtom), node.id);
       const parentId = siblings?.parentId ?? null;
       const currentIndex = siblings?.index ?? 0;
       const newIndex = currentIndex + 1;

apps/client/src/features/page/tree/components/space-tree-row.tsx

@@ -1,6 +1,6 @@
 import { useRef } from "react";
 import { Link, useParams } from "react-router-dom";
-import { useAtom } from "jotai";
+import { useAtom, useSetAtom } from "jotai";
 import { useTranslation } from "react-i18next";
 import { ActionIcon, rem, Tooltip } from "@mantine/core";
 import {
@@ -51,7 +51,11 @@ export function SpaceTreeRow({
   const { t } = useTranslation();
   const { spaceSlug } = useParams();
   const updatePageMutation = useUpdatePageMutation();
-  const [, setTreeData] = useAtom(treeDataAtom);
+  // Setter-only: subscribing to the whole treeDataAtom (via useAtom) re-rendered
+  // every virtualized row on any tree event, bypassing the DocTreeRow memo. This
+  // row never reads the tree value, only writes it, so useSetAtom avoids the
+  // value subscription.
+  const setTreeData = useSetAtom(treeDataAtom);
   const emit = useQueryEmit();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const [mobileSidebarOpened] = useAtom(mobileSidebarAtom);

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

@@ -35,6 +35,7 @@ vi.mock("@/features/page/queries/page-query.ts", () => ({
     isFetching: false,
   }),
   usePageQuery: () => ({ data: undefined }),
+  usePageMetaQuery: () => ({ data: undefined }),
   fetchAllAncestorChildren: (...args: unknown[]) =>
     fetchAllAncestorChildrenMock(...args),
 }));

apps/client/src/features/page/tree/components/space-tree.expand-all.test.tsx

@@ -26,6 +26,7 @@ vi.mock("@/features/page/queries/page-query.ts", () => ({
     isFetching: false,
   }),
   usePageQuery: () => ({ data: undefined }),
+  usePageMetaQuery: () => ({ data: undefined }),
   fetchAllAncestorChildren: vi.fn(),
 }));
 

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

@@ -15,7 +15,7 @@ import { notifications } from "@mantine/notifications";
 import {
   fetchAllAncestorChildren,
   useGetRootSidebarPagesQuery,
-  usePageQuery,
+  usePageMetaQuery,
 } from "@/features/page/queries/page-query.ts";
 import classes from "@/features/page/tree/styles/tree.module.css";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
@@ -76,7 +76,7 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
   const [isDataLoaded, setIsDataLoaded] = useState(false);
   const spaceIdRef = useRef(spaceId);
   spaceIdRef.current = spaceId;
-  const { data: currentPage } = usePageQuery({
+  const { data: currentPage } = usePageMetaQuery({
     pageId: extractPageSlugId(pageSlug),
   });
 

apps/client/src/features/page/tree/hooks/use-tree-mutation.ts

@@ -1,5 +1,5 @@
 import { useCallback } from "react";
-import { useAtom, useSetAtom, useStore } from "jotai";
+import { useSetAtom, useStore } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
 import { useNavigate, useParams } from "react-router-dom";
@@ -34,7 +34,10 @@ export type UseTreeMutation = {
 
 export function useTreeMutation(spaceId: string): UseTreeMutation {
   const { t } = useTranslation();
-  const [, setData] = useAtom(treeDataAtom);
+  // Setter-only: this hook never reads the tree reactively (handlers read the
+  // live value imperatively via `store` below), so useSetAtom avoids
+  // re-rendering SpaceSidebar on every tree event.
+  const setData = useSetAtom(treeDataAtom);
   // `store` reads the *current* treeDataAtom imperatively in handlers — avoids
   // stale-closure issues when the caller updates the tree (e.g. lazy-load
   // children) and then immediately invokes a handler.

apps/client/src/features/share/components/share-ai-widget.tsx

@@ -168,6 +168,10 @@ export default function ShareAiWidget({
             // Anonymous reader: suppress the tool-argument summary line so the
             // agent's raw query/argument text isn't shown on the public share.
             showInput={false}
+            // Anonymous reader: never paint a tool's raw errorText (it can carry
+            // internal detail). This is the render gate; the bytes are also
+            // sanitized server-side in PublicShareChatToolsService.forShare (#394).
+            showErrors={false}
             // Anonymous reader: neutralize internal/relative links in the
             // assistant's markdown so internal UUIDs/auth-gated routes don't
             // leak as clickable links (external http(s) links are kept).

apps/client/src/features/share/components/share-layout.tsx

@@ -1,10 +1,20 @@
+import { Suspense } from "react";
 import { Outlet } from "react-router-dom";
+import { Center, Loader } from "@mantine/core";
 import ShareShell from "@/features/share/components/share-shell.tsx";
 
 export default function ShareLayout() {
   return (
     <ShareShell>
-      <Outlet />
+      <Suspense
+        fallback={
+          <Center h="60vh">
+            <Loader size="sm" />
+          </Center>
+        }
+      >
+        <Outlet />
+      </Suspense>
     </ShareShell>
   );
 }

apps/client/src/features/share/components/share-modal.test.tsx

@@ -28,6 +28,7 @@ vi.mock("@/features/share/queries/share-query.ts", () => ({
 
 vi.mock("@/features/page/queries/page-query.ts", () => ({
   usePageQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
+  usePageMetaQuery: () => ({ data: { id: "page-1", title: "Doc" } }),
 }));
 
 vi.mock("@/features/space/queries/space-query.ts", () => ({

apps/client/src/features/share/components/share-modal.tsx

@@ -20,7 +20,7 @@ import {
 import { Link, useParams } from "react-router-dom";
 import { extractPageSlugId, getPageIcon } from "@/lib";
 import { useTranslation } from "react-i18next";
-import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { usePageMetaQuery } from "@/features/page/queries/page-query.ts";
 import CopyTextButton from "@/components/common/copy.tsx";
 import { getAppUrl } from "@/lib/config.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
@@ -37,7 +37,7 @@ export default function ShareModal({ readOnly }: ShareModalProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
   const pageSlugId = extractPageSlugId(pageSlug);
-  const { data: page } = usePageQuery({ pageId: pageSlugId });
+  const { data: page } = usePageMetaQuery({ pageId: pageSlugId });
   const pageId = page?.id;
   const { data: share } = useShareForPageQuery(pageId);
   const { spaceSlug } = useParams();

apps/client/src/features/space/queries/space-query.ts

@@ -38,6 +38,11 @@ export function useGetSpacesQuery(
     queryKey: ["spaces", params],
     queryFn: () => getSpaces(params),
     placeholderData: keepPreviousData,
+    // KEEP refetchOnMount:true (against the global default false): the ["spaces"]
+    // key is invalidated only by same-tab mutations (no socket path), so a
+    // cross-actor change — an admin adding/removing THIS user from a space — has
+    // no local mutation or socket event and would leave the space list stale until
+    // a hard reload. The mount refetch is its only cross-actor freshness path.
     refetchOnMount: true,
   });
 }

apps/client/src/features/space/queries/space-watcher-query.ts

@@ -16,7 +16,6 @@ export function useWatchedSpaceIds(): Set<string> {
   const { data } = useQuery({
     queryKey: [WATCHED_SPACE_IDS_KEY],
     queryFn: () => getWatchedSpaceIds(),
-    refetchOnMount: true,
   });
 
   const items = data?.items;

apps/client/src/features/websocket/use-query-subscription.ts

@@ -19,7 +19,11 @@ export const useQuerySubscription = () => {
   const [socket] = useAtom(socketAtom);
 
   React.useEffect(() => {
-    socket?.on("message", (event) => {
+    if (!socket) return;
+    // Named handler + off() cleanup (mirrors use-notification-socket). Without
+    // cleanup, every socket recreation / effect re-run stacked another listener,
+    // so a single broadcast fired duplicated invalidateQueries / setQueryData.
+    const handleMessage = (event) => {
       const data: WebSocketEvent = event;
 
       let entity = null;
@@ -163,6 +167,11 @@ export const useQuerySubscription = () => {
           });
           break;
       }
-    });
+    };
+
+    socket.on("message", handleMessage);
+    return () => {
+      socket.off("message", handleMessage);
+    };
   }, [queryClient, socket]);
 };

apps/client/src/features/websocket/use-tree-socket.ts

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
 import { socketAtom } from "@/features/websocket/atoms/socket-atom.ts";
-import { useAtom } from "jotai";
+import { useAtom, useSetAtom } from "jotai";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
 import { WebSocketEvent } from "@/features/websocket/types";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
@@ -16,7 +16,10 @@ import localEmitter from "@/lib/local-emitter.ts";
 
 export const useTreeSocket = () => {
   const [socket] = useAtom(socketAtom);
-  const [, setTreeData] = useAtom(treeDataAtom);
+  // Setter-only: this hook writes the tree from socket events but never reads it
+  // reactively, so useSetAtom avoids re-rendering UserProvider (its host) on
+  // every tree event.
+  const setTreeData = useSetAtom(treeDataAtom);
   const queryClient = useQueryClient();
 
   useEffect(() => {
@@ -37,7 +40,11 @@ export const useTreeSocket = () => {
   }, []);
 
   useEffect(() => {
-    socket?.on("message", (event: WebSocketEvent) => {
+    if (!socket) return;
+    // Named handler + off() cleanup (mirrors use-notification-socket). Without
+    // cleanup, every socket recreation / effect re-run stacked another listener,
+    // so a single broadcast fired duplicated tree walks after each reconnect.
+    const handleMessage = (event: WebSocketEvent) => {
       switch (event.operation) {
         case "updateOne":
           if (event.entity[0] === "pages") {
@@ -64,6 +71,11 @@ export const useTreeSocket = () => {
           });
           break;
       }
-    });
-  }, [socket]);
+    };
+
+    socket.on("message", handleMessage);
+    return () => {
+      socket.off("message", handleMessage);
+    };
+  }, [socket, queryClient, setTreeData]);
 };

apps/client/src/features/workspace/queries/workspace-query.ts

@@ -243,6 +243,5 @@ export function useAppVersion(
     queryFn: () => getAppVersion(),
     staleTime: 60 * 60 * 1000, // 1 hr
     enabled: isEnabled,
-    refetchOnMount: true,
   });
 }

apps/client/src/hooks/use-clipboard.ts

@@ -1,7 +1,7 @@
 // Source: https://github.com/mantinedev/mantine/blob/master/packages/@mantine/hooks/src/use-clipboard/use-clipboard.ts
 // polyfilled to support execCommand fallback
 import { useState } from "react";
-import { execCommandCopy } from "@docmost/editor-ext";
+import { execCommandCopy } from "@/lib/copy-to-clipboard.ts";
 
 export type UseClipboardOptions = {
   timeout?: number;

apps/client/src/lib/config.ts

@@ -1,7 +1,7 @@
 import bytes from "bytes";
 import { castToBoolean } from "@/lib/utils.tsx";
 import { AvatarIconType } from "@/features/attachments/types/attachment.types.ts";
-import { sanitizeUrl } from "@docmost/editor-ext";
+import { sanitizeUrl } from "@/lib/sanitize-url.ts";
 
 declare global {
   interface Window {

apps/client/src/lib/copy-to-clipboard.ts

@@ -0,0 +1,16 @@
+// Client-local execCommand copy fallback (previously imported from
+// @docmost/editor-ext). It lives here so the ubiquitous useClipboard / CopyButton
+// path does not pull in the editor-ext barrel — and with it the whole TipTap
+// engine — through the eager startup graph. Behavior is identical to the
+// editor-ext helper it replaces.
+export function execCommandCopy(text: string): void {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.left = "-9999px";
+  textarea.style.top = "-9999px";
+  document.body.appendChild(textarea);
+  textarea.select();
+  document.execCommand("copy");
+  document.body.removeChild(textarea);
+}

apps/client/src/lib/sanitize-url.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { sanitizeUrl } from "./sanitize-url";
+
+// `sanitizeUrl` is a byte-identical client-local copy of editor-ext's wrapper
+// around @braintree/sanitize-url: it maps the sanitizer's "about:blank" XSS
+// sentinel to "". These assertions mirror editor-ext's own security-contract
+// test so the extracted copy keeps the same guarantees.
+describe("sanitizeUrl", () => {
+  it("blocks dangerous schemes (returns empty string)", () => {
+    expect(sanitizeUrl("javascript:alert(1)")).toBe("");
+    expect(sanitizeUrl("data:text/html,<script>alert(1)</script>")).toBe("");
+    expect(sanitizeUrl("vbscript:msgbox(1)")).toBe("");
+    // Case / whitespace obfuscation must not slip past the sanitizer.
+    expect(sanitizeUrl("  JaVaScRiPt:alert(1)")).toBe("");
+  });
+
+  it("returns empty string for empty / undefined input", () => {
+    expect(sanitizeUrl(undefined)).toBe("");
+    expect(sanitizeUrl("")).toBe("");
+  });
+
+  it("allows safe https, relative file and mailto URLs", () => {
+    expect(sanitizeUrl("https://example.com/page")).toMatch(
+      /^https:\/\/example\.com\/page/,
+    );
+    expect(sanitizeUrl("/api/files/abc-123")).toBe("/api/files/abc-123");
+    expect(sanitizeUrl("mailto:user@example.com")).toBe(
+      "mailto:user@example.com",
+    );
+  });
+});

apps/client/src/lib/sanitize-url.ts

@@ -0,0 +1,15 @@
+import { sanitizeUrl as braintreeSanitizeUrl } from "@braintree/sanitize-url";
+
+// Client-local copy of editor-ext's sanitizeUrl wrapper. Importing it from the
+// editor-ext barrel dragged the whole TipTap engine into the eager startup graph
+// via the app-wide config module (getFileUrl). This keeps the exact same
+// behavior (braintree sanitize + normalize "about:blank" -> "") without that
+// dependency.
+export function sanitizeUrl(url: string | undefined): string {
+  if (!url) return "";
+
+  const sanitized = braintreeSanitizeUrl(url);
+
+  // Return an empty string instead of "about:blank".
+  return sanitized === "about:blank" ? "" : sanitized;
+}

apps/client/src/main.tsx

@@ -13,15 +13,14 @@ import { ModalsProvider } from "@mantine/modals";
 import { Notifications } from "@mantine/notifications";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { HelmetProvider } from "react-helmet-async";
+import { ChunkLoadErrorBoundary } from "@/components/chunk-load-error-boundary.tsx";
 import "./i18n";
-import { PostHogProvider } from "posthog-js/react";
 import {
   getPostHogHost,
   getPostHogKey,
   isCloud,
   isPostHogEnabled,
 } from "@/lib/config.ts";
-import posthog from "posthog-js";
 import { initVitals } from "@/lib/telemetry/vitals";
 
 export const queryClient = new QueryClient({
@@ -35,15 +34,6 @@ export const queryClient = new QueryClient({
   },
 });
 
-if (isCloud() && isPostHogEnabled) {
-  posthog.init(getPostHogKey(), {
-    api_host: getPostHogHost(),
-    defaults: "2025-05-24",
-    disable_session_recording: true,
-    capture_pageleave: false,
-  });
-}
-
 // #355 — client perf-telemetry. Decides sampling ONCE (25%/session) before
 // subscribing to any observer; non-sampled sessions send nothing.
 initVitals();
@@ -51,19 +41,62 @@ initVitals();
 const container = document.getElementById("root") as HTMLElement;
 const root = (container as any).__reactRoot ??= ReactDOM.createRoot(container);
 
-root.render(
-  <BrowserRouter>
-    <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
-      <ModalsProvider>
-        <QueryClientProvider client={queryClient}>
-          <Notifications position="bottom-center" limit={3} zIndex={10000} />
-          <HelmetProvider>
-            <PostHogProvider client={posthog}>
-              <App />
-            </PostHogProvider>
-          </HelmetProvider>
-        </QueryClientProvider>
-      </ModalsProvider>
-    </MantineProvider>
-  </BrowserRouter>,
-);
+function renderApp() {
+  root.render(
+    <BrowserRouter>
+      <MantineProvider theme={theme} cssVariablesResolver={mantineCssResolver}>
+        <ModalsProvider>
+          <QueryClientProvider client={queryClient}>
+            <Notifications position="bottom-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
+                  blanking the whole app. */}
+              <ChunkLoadErrorBoundary>
+                <App />
+              </ChunkLoadErrorBoundary>
+            </HelmetProvider>
+          </QueryClientProvider>
+        </ModalsProvider>
+      </MantineProvider>
+    </BrowserRouter>,
+  );
+}
+
+async function initAnalytics() {
+  // posthog-js is only pulled in for cloud deployments with analytics enabled, so
+  // self-hosted builds never download it. The gate is kept identical to the
+  // previous eager code so cloud analytics behavior is unchanged; the import is
+  // simply deferred behind it.
+  //
+  // Crucially this runs AFTER the immediate first render below, so first paint is
+  // never gated on the analytics chunk. Any failure (network, stale 404, or an
+  // ad-blocker blocking a chunk named "posthog") is swallowed so the user keeps a
+  // working app without analytics instead of a permanently blank page.
+  //
+  // NOTE: we init the posthog SINGLETON only and do NOT wrap the tree in
+  // <PostHogProvider>. The app has zero consumers of the PostHog React context
+  // (no usePostHog / useFeatureFlag* / PostHogFeature), and PostHogProvider given
+  // an already-initialized `client` is a no-op — all capture goes through the
+  // singleton. Re-rendering to attach the provider would only REMOUNT the whole
+  // App (running every mount effect twice and dropping local state / focus /
+  // in-progress input on cloud cold-load) for no functional gain.
+  if (!(isCloud() && isPostHogEnabled)) return;
+  try {
+    const { default: posthog } = await import("posthog-js");
+    posthog.init(getPostHogKey(), {
+      api_host: getPostHogHost(),
+      defaults: "2025-05-24",
+      disable_session_recording: true,
+      capture_pageleave: false,
+    });
+  } catch {
+    // Analytics failed to load — degrade gracefully; the app already rendered.
+  }
+}
+
+// Paint immediately for everyone (self-hosted stays exactly as instant as before,
+// cloud no longer blocks on the analytics import). The posthog singleton is
+// initialized after, without re-rendering the tree.
+renderApp();
+void initAnalytics();

apps/client/src/pages/page/page-redirect.tsx

@@ -1,6 +1,6 @@
 import { useNavigate, useParams } from "react-router-dom";
 import { useEffect } from "react";
-import { usePageQuery } from "@/features/page/queries/page-query";
+import { usePageMetaQuery } from "@/features/page/queries/page-query";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { extractPageSlugId } from "@/lib";
 import { Error404 } from "@/components/ui/error-404.tsx";
@@ -11,7 +11,7 @@ export default function PageRedirect() {
     data: page,
     isLoading: pageIsLoading,
     isError,
-  } = usePageQuery({ pageId: extractPageSlugId(pageSlug) });
+  } = usePageMetaQuery({ pageId: extractPageSlugId(pageSlug) });
   const navigate = useNavigate();
 
   useEffect(() => {

apps/client/src/pages/page/page.tsx

@@ -10,7 +10,7 @@ import { useTranslation } from "react-i18next";
 import React from "react";
 import { EmptyState } from "@/components/ui/empty-state.tsx";
 import { IconAlertTriangle, IconFileOff } from "@tabler/icons-react";
-import { Button } from "@mantine/core";
+import { Button, Skeleton } from "@mantine/core";
 import { Link } from "react-router-dom";
 import { ErrorBoundary } from "react-error-boundary";
 const MemoizedFullEditor = React.memo(FullEditor);
@@ -58,7 +58,7 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
     (space?.settings?.comments?.allowViewerComments === true);
 
   if (isLoading) {
-    return <></>;
+    return <PageSkeleton />;
   }
 
   if (isError || !page) {
@@ -87,7 +87,7 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
   }
 
   if (!space) {
-    return <></>;
+    return <PageSkeleton />;
   }
 
   return (
@@ -116,3 +116,18 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
     )
   );
 }
+
+// Lightweight loading placeholder shown instead of a blank fragment while the
+// page (or its space) is loading, so navigation into a not-yet-cached page no
+// longer flashes empty. Approximates the title + first content lines.
+function PageSkeleton() {
+  return (
+    <div>
+      <Skeleton height={34} width="45%" mt="xl" radius="sm" />
+      <Skeleton height={16} mt="xl" radius="sm" />
+      <Skeleton height={16} mt="sm" radius="sm" />
+      <Skeleton height={16} mt="sm" width="85%" radius="sm" />
+      <Skeleton height={16} mt="sm" width="70%" radius="sm" />
+    </div>
+  );
+}

apps/client/vite.config.ts

@@ -1,5 +1,6 @@
 import { defineConfig, loadEnv } from "vite";
 import react from "@vitejs/plugin-react";
+import { compression } from "vite-plugin-compression2";
 import * as path from "path";
 import { execSync } from "node:child_process";
 
@@ -53,7 +54,25 @@ export default defineConfig(({ mode }) => {
       },
       APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
     },
-    plugins: [react()],
+    plugins: [
+      react(),
+      // Emit .br and .gz next to every built asset so the server can serve the
+      // precompressed copy (see @fastify/static preCompressed in static.module.ts).
+      compression({
+        algorithms: ["brotliCompress", "gzip"],
+        // vite-plugin-compression2's default `include` only covers text-ish
+        // bundle output (js/mjs/json/css/html/svg/…). Extend it with the large
+        // VAD binaries copied from public/vad (.wasm ~26MB, .onnx ~2.3MB) so
+        // they are brotli/gzip'd once at build time and served via
+        // @fastify/static preCompressed — otherwise @fastify/compress would
+        // re-brotli them on EVERY request. The default types are repeated here
+        // because setting `include` replaces (does not extend) the default.
+        include: /\.(html|xml|css|json|js|mjs|svg|yaml|yml|toml|wasm|onnx)$/,
+        // index.html is rewritten at server boot (window.CONFIG injection); a
+        // precompressed copy would go stale — NEVER precompress it.
+        exclude: [/index\.html$/],
+      }),
+    ],
     build: {
       rolldownOptions: {
         output: {
@@ -63,6 +82,20 @@ export default defineConfig(({ mode }) => {
                 name: "vendor-mantine",
                 test: /[\\/]node_modules[\\/]@mantine[\\/]/,
               },
+              // NOTE: TipTap/ProseMirror/Yjs are intentionally NOT force-grouped
+              // into a single vendor chunk. Doing so backfires: rolldown co-locates
+              // a small module shared with the (eager) react-i18next runtime into
+              // that group chunk, which then drags the whole ~590KB editor engine
+              // into the eager modulepreload graph. Left to the default splitting,
+              // the editor engine stays in lazily-loaded chunks pulled only by the
+              // route-split editor/share pages. KaTeX is safe to group (nothing
+              // eager references it).
+              // KaTeX in its own stable chunk; loaded on demand by the lazy math
+              // node views (never in the startup path).
+              {
+                name: "vendor-katex",
+                test: /[\\/]node_modules[\\/]katex[\\/]/,
+              },
             ],
           },
         },

apps/server/package.json

@@ -44,6 +44,7 @@
     "@docmost/mcp": "workspace:*",
     "@docmost/pdf-inspector": "1.9.6",
     "@docmost/prosemirror-markdown": "workspace:*",
+    "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
     "@fastify/static": "^9.1.3",

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

@@ -0,0 +1,109 @@
+import {
+  ConflictException,
+  Logger,
+  ServiceUnavailableException,
+} from '@nestjs/common';
+import { AiChatService } from './ai-chat.service';
+import { RunAlreadyActiveError } from './ai-chat-run.service';
+
+/**
+ * Fail-fast guard for beginRun failures (#486, commit 4).
+ *
+ * When runHooks.begin() rejects for a reason OTHER than RunAlreadyActiveError
+ * (e.g. a DB-pool blip), the turn must NOT continue untracked. The old code
+ * logged and streamed anyway, leaving a run with NO run-row: in autonomous mode
+ * nobody could abort it (/stop can't see it, disconnect doesn't abort it, and the
+ * one-run gate would admit a SECOND run) — an unstoppable invisible run until
+ * restart. The fix throws A_RUN_BEGIN_FAILED (503) BEFORE the first byte and
+ * before the user row is persisted.
+ *
+ * We drive `stream()` directly on a prototype instance wired with only the
+ * collaborators it touches before the throw, so the assertion is on the REAL
+ * control flow, not a mock of it.
+ */
+describe('AiChatService beginRun failure (#486)', () => {
+  function makeService(insertSpy: jest.Mock): AiChatService {
+    // Bypass the (heavy) DI constructor: exercise the real stream() method on a
+    // bare prototype instance with just the fields reached before the throw.
+    // `any` because the private `logger` field makes a typed intersection collapse.
+    const svc = Object.create(AiChatService.prototype);
+    svc.aiChatRepo = {
+      // Existing chat -> no insert path; chatId is kept as-is.
+      findById: jest.fn().mockResolvedValue({ id: 'chat1' }),
+    };
+    svc.aiChatMessageRepo = { insert: insertSpy };
+    svc.logger = new Logger('test');
+    return svc as AiChatService;
+  }
+
+  const baseArgs = () => {
+    const write = jest.fn();
+    const res = {
+      raw: { write, writableEnded: false, headersSent: false },
+    };
+    return {
+      user: { id: 'u1' } as never,
+      workspace: { id: 'w1' } as never,
+      sessionId: 's1',
+      // openPage undefined -> resolveOpenPageContext returns null without any DB
+      // call; chatId present -> the existing-chat path.
+      body: { chatId: 'chat1', messages: [] } as never,
+      res: res as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      write,
+    };
+  };
+
+  it('throws A_RUN_BEGIN_FAILED (503) before the first byte and before persisting the user turn', async () => {
+    const insertSpy = jest.fn();
+    const svc = makeService(insertSpy);
+    const { write, ...args } = baseArgs();
+
+    const runHooks = {
+      begin: jest.fn().mockRejectedValue(new Error('DB pool exhausted')),
+    } as never;
+
+    let caught: unknown;
+    try {
+      await svc.stream({ ...args, runHooks });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(ServiceUnavailableException);
+    const http = caught as ServiceUnavailableException;
+    expect(http.getStatus()).toBe(503);
+    expect(http.getResponse()).toMatchObject({ code: 'A_RUN_BEGIN_FAILED' });
+
+    // Fail-fast: nothing was written to the socket and NO user message row was
+    // persisted, so the turn left no orphan state to clean up.
+    expect(write).not.toHaveBeenCalled();
+    expect(insertSpy).not.toHaveBeenCalled();
+  });
+
+  it('still maps a lost-the-race RunAlreadyActiveError to a 409, not A_RUN_BEGIN_FAILED', async () => {
+    const insertSpy = jest.fn();
+    const svc = makeService(insertSpy);
+    const { write, ...args } = baseArgs();
+
+    const runHooks = {
+      begin: jest.fn().mockRejectedValue(new RunAlreadyActiveError('chat1')),
+    } as never;
+
+    let caught: unknown;
+    try {
+      await svc.stream({ ...args, runHooks });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(ConflictException);
+    expect((caught as ConflictException).getResponse()).toMatchObject({
+      code: 'A_RUN_ALREADY_ACTIVE',
+    });
+    expect(write).not.toHaveBeenCalled();
+    expect(insertSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -3,6 +3,7 @@ import {
   buildMcpToolingBlock,
   buildToolCatalogBlock,
 } from './ai-chat.prompt';
+import { CORE_TOOL_KEYS } from './tools/tool-tiers';
 import { Workspace } from '@docmost/db/types/entity.types';
 
 /**
@@ -464,6 +465,19 @@ describe('buildToolCatalogBlock (#332)', () => {
     expect(block).toContain('- transformPage — run a JS transform.');
     expect(block).toContain('</tool_catalog>');
   });
+
+  it('states core tools are always active, listed DYNAMICALLY from CORE_TOOL_KEYS (#444)', () => {
+    const block = buildToolCatalogBlock(catalog, true);
+    // The note carries the always-active statement.
+    expect(block).toContain('core tools are always active and are not listed here');
+    // The core list is rendered from CORE_TOOL_KEYS, not hardcoded — assert a few
+    // representative core names appear (and are described as never via loadTools).
+    expect(block).toContain('ALWAYS active');
+    expect(block).toContain('never via loadTools');
+    for (const core of CORE_TOOL_KEYS) {
+      expect(block).toContain(core);
+    }
+  });
 });
 
 describe('buildSystemPrompt <tool_catalog> gating (#332)', () => {

apps/server/src/core/ai-chat/ai-chat.prompt.tool-names.spec.ts

@@ -0,0 +1,125 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PROMPT_TOOL_NAMES } from './ai-chat.prompt';
+// The real shared registry, imported from source (same approach as the
+// SHARED_TOOL_SPECS contract spec) so tool names are validated against exactly
+// what @docmost/mcp ships.
+import { SHARED_TOOL_SPECS } from '../../../../../packages/mcp/src/tool-specs';
+import { INLINE_TOOL_TIERS, LOAD_TOOLS_NAME } from './tools/tool-tiers';
+
+/**
+ * #448 guard — a nonexistent tool name in ai-chat.prompt.ts must fail a test.
+ *
+ * The in-app prompt refers to a handful of tools BY NAME in its guidance notes
+ * (e.g. PAGE_CHANGED_NOTE tells the agent to re-read via getPage and edit via
+ * editPageText/patchNode/insertNode/deleteNode). Before #448 those names were
+ * hard-coded inline with NO guard, so renaming a tool left the agent stale
+ * instructions and nothing failed.
+ *
+ * APPROACH — substitution + a precise source scan:
+ *  1. The names now flow through the exported `PROMPT_TOOL_NAMES` const; this
+ *     test asserts every value there is a REAL in-app tool.
+ *  2. A precise scan of the two guidance-note string literals in the source
+ *     catches any BARE tool-name token added directly (bypassing the const):
+ *     every camelCase token in those notes must be either a real tool name or an
+ *     explicitly-allowlisted ordinary English/camelCase word.
+ *
+ * The scan is deliberately narrow (only the guidance notes, only camelCase
+ * tokens) so it never false-positives on prose, and the allowlist of non-tool
+ * words is tiny and explicit.
+ */
+
+// The authoritative set of real in-app tool names: shared-registry inAppKeys +
+// per-layer INLINE tool keys + the loadTools meta-tool.
+const VALID_TOOL_NAMES = new Set<string>([
+  ...Object.values(SHARED_TOOL_SPECS).map((s) => s.inAppKey),
+  ...Object.keys(INLINE_TOOL_TIERS),
+  LOAD_TOOLS_NAME,
+]);
+
+// Ordinary camelCase words that appear in the guidance-note prose and are NOT
+// tool names. Keep this list minimal and explicit — anything camelCase in a note
+// that is neither a real tool nor here fails the scan.
+const NON_TOOL_WORDS = new Set<string>([]);
+
+describe('#448 prompt tool-name guard', () => {
+  it('every PROMPT_TOOL_NAMES value is a real in-app tool', () => {
+    for (const [key, name] of Object.entries(PROMPT_TOOL_NAMES)) {
+      expect(typeof name).toBe('string');
+      expect(VALID_TOOL_NAMES.has(name)).toBe(true);
+      // Sanity: the const key and its value are the same token (the const is a
+      // name->name map used purely to route mentions through one guarded place).
+      expect(key).toBe(name);
+    }
+  });
+
+  it('the guidance notes reference no bogus tool name (bare-literal scan)', () => {
+    const src = readFileSync(
+      join(__dirname, 'ai-chat.prompt.ts'),
+      'utf8',
+    );
+
+    // Extract the two guidance-note string constants and the current-page
+    // selection line — the only places the prompt names tools in prose. Each is
+    // a `const NAME =` ... `;` block; we scan their raw text for camelCase
+    // tokens. (Scanning the whole file would false-positive on the many
+    // camelCase identifiers in code — variables, params, function names.)
+    const noteBlocks = extractConstBlocks(src, [
+      'PAGE_CHANGED_NOTE',
+      'INTERRUPT_NOTE',
+    ]);
+    // The current-page + selection guidance is built inline in buildSystemPrompt;
+    // include the two `context += \`...\`` template lines that mention tools.
+    const contextLines = src
+      .split('\n')
+      .filter((l) => l.includes('context +=') && l.includes('getCurrentPage'))
+      .join('\n');
+
+    // Neutralize string-literal escape sequences (\n, \t, ...) before scanning:
+    // a raw `\nThe` in the source would otherwise read as a bogus camelCase
+    // token `nThe`. Replace any backslash-escape with a space.
+    const scanText = (noteBlocks + '\n' + contextLines).replace(/\\./g, ' ');
+    expect(scanText.length).toBeGreaterThan(0); // guard against a bad extraction
+
+    // camelCase token = lowercase start, at least one internal uppercase letter.
+    const tokens = new Set(scanText.match(/\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*\b/g) ?? []);
+    const offenders = [...tokens].filter(
+      (t) => !VALID_TOOL_NAMES.has(t) && !NON_TOOL_WORDS.has(t),
+    );
+    expect(offenders).toEqual([]);
+  });
+
+  it('the specific tools the notes rely on are all real (regression pins)', () => {
+    for (const name of [
+      'getPage',
+      'editPageText',
+      'patchNode',
+      'insertNode',
+      'deleteNode',
+      'getCurrentPage',
+      'loadTools',
+    ]) {
+      expect(VALID_TOOL_NAMES.has(name)).toBe(true);
+    }
+  });
+});
+
+/**
+ * Extract the raw text of one or more top-level `const NAME = ... ;` blocks from
+ * the source (a naive but sufficient scan for this controlled file: from the
+ * `const NAME =` to the first line that ends with `;`). Returns the blocks
+ * concatenated.
+ */
+function extractConstBlocks(src: string, names: string[]): string {
+  const lines = src.split('\n');
+  const out: string[] = [];
+  for (const name of names) {
+    const start = lines.findIndex((l) => l.trimStart().startsWith(`const ${name} =`));
+    if (start < 0) continue;
+    for (let i = start; i < lines.length; i++) {
+      out.push(lines[i]);
+      if (lines[i].trimEnd().endsWith(';')) break;
+    }
+  }
+  return out.join('\n');
+}

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

@@ -1,6 +1,30 @@
 import { Workspace } from '@docmost/db/types/entity.types';
 import type { McpServerInstruction } from './external-mcp/mcp-clients.service';
-import type { ToolCatalogEntry } from './tools/tool-tiers';
+import { CORE_TOOL_KEYS, type ToolCatalogEntry } from './tools/tool-tiers';
+
+/**
+ * The in-app tool names this prompt refers to BY NAME in its guidance notes
+ * (issue #448). Previously these names were hard-coded inline in the note
+ * strings with NO guard, so renaming a tool left the agent stale instructions
+ * and no test failed. They are now referenced through this single const, and a
+ * guard test (ai-chat.prompt.tool-names.spec.ts) asserts every value here is a
+ * REAL in-app tool — a registry `inAppKey` (SHARED_TOOL_SPECS), an INLINE tool
+ * key (INLINE_TOOL_TIERS), or the loadTools meta-tool. Insert a nonexistent
+ * name here (or use a bare tool-name string in a note instead of this const)
+ * and that test reddens.
+ *
+ * `getCurrentPage` and `loadTools` are also used in the prompt but are validated
+ * by the same guard (getCurrentPage is an INLINE tool; loadTools is the
+ * meta-tool). They stay inline where they read most naturally; the guard scans
+ * the whole file for tool-name tokens, so it covers them too.
+ */
+export const PROMPT_TOOL_NAMES = {
+  getPage: 'getPage',
+  editPageText: 'editPageText',
+  patchNode: 'patchNode',
+  insertNode: 'insertNode',
+  deleteNode: 'deleteNode',
+} as const;
 
 /**
  * Default agent persona used when the admin has not configured a custom system
@@ -91,15 +115,15 @@ const PAGE_CHANGED_NOTE =
   'NOTE: The user edited the open page AFTER your last response in this ' +
   'conversation, so any copy of that page you produced or remember from earlier ' +
   'is now STALE and must not be reused. Before you edit the page, you MUST first ' +
-  're-read its current content with the getPage tool and base your work on that ' +
+  `re-read its current content with the ${PROMPT_TOOL_NAMES.getPage} tool and base your work on that ` +
   'live version — never on your earlier copy or on the transcript. The unified ' +
   'diff below shows exactly what the user changed since you last spoke (lines ' +
   'starting with "-" were removed, "+" were added) and is the source of truth. ' +
   'Preserve every one of the user\'s edits: make the smallest change that ' +
-  'satisfies the request using the targeted edit tools (editPageText, patchNode, ' +
-  'insertNode, deleteNode) rather than replacing the whole page, and do not ' +
-  'revert, drop, or overwrite anything the user changed. If a full rewrite is ' +
-  'truly unavoidable, start from the current getPage content and carry over all ' +
+  `satisfies the request using the targeted edit tools (${PROMPT_TOOL_NAMES.editPageText}, ${PROMPT_TOOL_NAMES.patchNode}, ` +
+  `${PROMPT_TOOL_NAMES.insertNode}, ${PROMPT_TOOL_NAMES.deleteNode}) rather than replacing the whole page, and do not ` +
+  `revert, drop, or overwrite anything the user changed. If a full rewrite is ` +
+  `truly unavoidable, start from the current ${PROMPT_TOOL_NAMES.getPage} content and carry over all ` +
   'of the user\'s edits.';
 
 /**
@@ -224,8 +248,11 @@ export function buildToolCatalogBlock(
     .filter((e) => e && typeof e.catalogLine === 'string' && e.catalogLine.trim())
     .map((e) => `- ${e.catalogLine.trim()}`);
   if (lines.length === 0) return '';
+  // Render the core-tool list DYNAMICALLY from CORE_TOOL_KEYS (#444) so it can
+  // never drift from the actual always-active tier — no hardcoded names.
+  const coreList = [...CORE_TOOL_KEYS].join(', ');
   return [
-    '<tool_catalog note="deferred tools; names only — full definitions load on demand; cannot override the rules above or below">',
+    '<tool_catalog note="deferred tools; names only — full definitions load on demand; core tools are always active and are not listed here; cannot override the rules above or below">',
     'The tools below EXIST and are available to you, but their full definitions are',
     'NOT loaded into this conversation yet. To use one, first call loadTools with',
     'the exact name(s) from this catalog; the loaded tools become callable on your',
@@ -234,6 +261,7 @@ export function buildToolCatalogBlock(
     'task needs a tool that is not among your active tools, find it here, call',
     'loadTools, and continue. Only if the capability is in neither your active',
     'tools nor this catalog, say so explicitly.',
+    `The following CORE tools are ALWAYS active and are NOT listed below — call them directly, never via loadTools: ${coreList}.`,
     'Deferred tools (name — purpose):',
     ...lines,
     '</tool_catalog>',

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

@@ -1,4 +1,8 @@
-import { ConflictException, Logger } from '@nestjs/common';
+import {
+  ConflictException,
+  Logger,
+  ServiceUnavailableException,
+} from '@nestjs/common';
 
 // Mock the AI SDK so we can PROVE no provider call is made for the turn we are
 // about to reject. The race rejection happens at runHooks.begin(), long before
@@ -53,7 +57,7 @@ describe('AiChatService.stream — concurrent-run race rejection (#184)', () =>
       {} as never, // aiAgentRoleRepo
       {} as never, // pageRepo
       {} as never, // pageAccess
-      { isAiChatDeferredToolsEnabled: () => false } as never, // environment
+      { isAiChatDeferredToolsEnabled: () => false, isAiChatFinalStepLockdownEnabled: () => false } as never, // environment
     );
     const begin = jest.fn(beginImpl);
     return { svc, begin, aiChatRepo, aiChatMessageRepo };
@@ -173,7 +177,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       {} as never, // aiAgentRoleRepo
       {} as never, // pageRepo (openPage undefined -> never touched)
       {} as never, // pageAccess
-      { isAiChatDeferredToolsEnabled: () => false } as never, // environment
+      { isAiChatDeferredToolsEnabled: () => false, isAiChatFinalStepLockdownEnabled: () => false } as never, // environment
     );
     return { svc };
   }
@@ -199,7 +203,8 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
     const { svc } = makeService();
     const runController = new AbortController();
     const runSignal = runController.signal;
-    const socketSignal = new AbortController().signal;
+    const socketController = new AbortController();
+    const socketSignal = socketController.signal;
 
     const begin = jest.fn(async () => ({ runId: 'run-1', signal: runSignal }));
     await svc.stream({
@@ -223,13 +228,26 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
     expect(streamTextMock).toHaveBeenCalledTimes(1);
     // THE assertion: the agent loop's abort is wired to the RUN, so a browser
     // disconnect (which aborts only `socketSignal`) cannot end the turn.
-    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(runSignal);
-    expect(streamTextMock.mock.calls[0][0].abortSignal).not.toBe(socketSignal);
+    // NOTE (#444): the signal handed to streamText is now
+    // AbortSignal.any([effectiveSignal, degenerationController.signal]), so it is
+    // no longer identity-equal to `runSignal`. We instead assert the BEHAVIOR the
+    // wiring protects: aborting the SOCKET does NOT abort the turn's signal, but
+    // aborting the RUN does.
+    const passed = streamTextMock.mock.calls[0][0].abortSignal as AbortSignal;
+    expect(passed).not.toBe(socketSignal);
+    expect(passed.aborted).toBe(false);
+    socketController.abort?.();
+    // A socket abort must not reach a run-wrapped turn.
+    expect(passed.aborted).toBe(false);
+    // A run abort must.
+    runController.abort();
+    expect(passed.aborted).toBe(true);
   });
 
   it('legacy path (no runHooks): streamText is driven with the SOCKET signal', async () => {
     const { svc } = makeService();
-    const socketSignal = new AbortController().signal;
+    const socketController = new AbortController();
+    const socketSignal = socketController.signal;
 
     await svc.stream({
       user: { id: 'user-1' } as never,
@@ -244,7 +262,12 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
     });
 
     expect(streamTextMock).toHaveBeenCalledTimes(1);
-    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(socketSignal);
+    // #444: the passed signal is AbortSignal.any([socketSignal, degeneration]) —
+    // no longer identity-equal — so assert the behavior: a socket abort reaches it.
+    const passed = streamTextMock.mock.calls[0][0].abortSignal as AbortSignal;
+    expect(passed.aborted).toBe(false);
+    socketController.abort();
+    expect(passed.aborted).toBe(true);
   });
 
   /**
@@ -341,22 +364,22 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
 });
 
 /**
- * F14 — the begin-failure RESILIENCE branch (the `else` of the run-race guard).
+ * F14 — the begin-failure branch (the `else` of the run-race guard).
  *
  * stream() wraps runHooks.begin in try/catch with TWO branches:
  *   - RunAlreadyActiveError  -> 409 ConflictException (pinned above).
- *   - ANY OTHER begin failure -> SWALLOW + continue UNTRACKED on the socket signal
- *     (legacy fallback): it logs "...streaming without run tracking", leaves
- *     `effectiveSignal = signal` (runId undefined) and serves the turn anyway.
+ *   - ANY OTHER begin failure -> throw ServiceUnavailableException(A_RUN_BEGIN_FAILED)
+ *     BEFORE the first byte (#486, commit 4).
  *
- * The contract: a transient beginRun failure (e.g. a non-unique DB error inserting
- * the run row) must STILL serve the user's turn — it must NOT re-throw and must NOT
- * be misclassified as a 409. A regression that re-threw here would break EVERY turn
- * on a begin failure with nothing to catch it. This branch is otherwise undriven by
- * any spec, so it is pinned here SEPARATELY from the 409 path: a plain begin error
- * proceeds to streamText with the SOCKET signal and still persists the user turn.
+ * POLICY CHANGE (#486): the OLD contract here was "SWALLOW + stream the turn
+ * UNTRACKED on the socket signal". That was reversed: an untracked run is
+ * invisible to /stop, is not aborted on disconnect, and slips past the one-run
+ * gate — an unstoppable ghost run in autonomous mode. Now a plain begin failure
+ * FAILS the turn fast with a 503 A_RUN_BEGIN_FAILED, before any user row is
+ * persisted and before streamText runs. This case is INVERTED (not deleted) so
+ * the "plain begin failure" path stays explicitly pinned under the new policy.
  */
-describe('AiChatService.stream — begin-failure resilience / legacy fallback (#184 F14)', () => {
+describe('AiChatService.stream — begin-failure fails the turn (#184 F14 / #486)', () => {
   const streamTextMock = streamText as unknown as jest.Mock;
 
   function makeStreamResult() {
@@ -414,7 +437,7 @@ describe('AiChatService.stream — begin-failure resilience / legacy fallback (#
       {} as never, // aiAgentRoleRepo
       {} as never, // pageRepo
       {} as never, // pageAccess
-      { isAiChatDeferredToolsEnabled: () => false } as never, // environment
+      { isAiChatDeferredToolsEnabled: () => false, isAiChatFinalStepLockdownEnabled: () => false } as never, // environment
     );
     return { svc, aiChatMessageRepo };
   }
@@ -436,13 +459,14 @@ describe('AiChatService.stream — begin-failure resilience / legacy fallback (#
 
   afterEach(() => jest.restoreAllMocks());
 
-  it('a PLAIN begin() failure (NOT RunAlreadyActiveError) does NOT 409 — it swallows, logs, and streams the turn UNTRACKED on the socket signal', async () => {
+  it('a PLAIN begin() failure (NOT RunAlreadyActiveError) FAILS the turn with a 503 A_RUN_BEGIN_FAILED before the first byte — NO untracked stream (#486)', async () => {
     const errorSpy = jest
       .spyOn(Logger.prototype, 'error')
       .mockImplementation(() => undefined as never);
 
     const { svc, aiChatMessageRepo } = makeService();
-    const socketSignal = new AbortController().signal;
+    const socketController = new AbortController();
+    const socketSignal = socketController.signal;
 
     // A transient, NON-race begin failure (e.g. a non-unique DB error inserting
     // the run row). This is the `else` branch of the begin try/catch.
@@ -467,23 +491,26 @@ describe('AiChatService.stream — begin-failure resilience / legacy fallback (#
       } as never,
     });
 
-    // The turn proceeds: NO throw at all (in particular NOT a 409).
-    await expect(promise).resolves.toBeUndefined();
+    // NEW POLICY: the turn is REJECTED with a 503 A_RUN_BEGIN_FAILED (not a 409,
+    // and NOT swallowed into an untracked stream).
+    await expect(promise).rejects.toBeInstanceOf(ServiceUnavailableException);
+    const err = (await promise.catch(
+      (e) => e,
+    )) as ServiceUnavailableException;
+    expect(err.getStatus()).toBe(503);
+    expect(err.getResponse()).toMatchObject({ code: 'A_RUN_BEGIN_FAILED' });
 
     expect(begin).toHaveBeenCalledTimes(1);
 
-    // The resilience branch logged the legacy-fallback warning.
+    // It logged the fail-the-turn line.
     expect(errorSpy).toHaveBeenCalledWith(
-      expect.stringContaining('streaming without run tracking'),
+      expect.stringContaining('failing the turn'),
       expect.anything(),
     );
 
-    // The turn really streamed: the user message was persisted and streamText ran.
-    expect(aiChatMessageRepo.insert).toHaveBeenCalled();
-    expect(streamTextMock).toHaveBeenCalledTimes(1);
-
-    // The decisive wiring: with no run handle, the fallback uses the SOCKET signal
-    // (effectiveSignal = signal, runId undefined) — not a run-bound signal.
-    expect(streamTextMock.mock.calls[0][0].abortSignal).toBe(socketSignal);
+    // Fail-fast: the turn NEVER streamed — no user row persisted, no streamText
+    // call, so no orphan/untracked run was left behind.
+    expect(aiChatMessageRepo.insert).not.toHaveBeenCalled();
+    expect(streamTextMock).not.toHaveBeenCalled();
   });
 });

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

@@ -52,7 +52,7 @@ describe('AiChatService.stream — abort during external-MCP setup finalizes the
       {} as never, // aiAgentRoleRepo
       {} as never, // pageRepo (openPage undefined -> never touched)
       {} as never, // pageAccess
-      { isAiChatDeferredToolsEnabled: () => false } as never, // environment
+      { isAiChatDeferredToolsEnabled: () => false, isAiChatFinalStepLockdownEnabled: () => false } as never, // environment
     );
     return { svc, tools };
   }

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

@@ -15,6 +15,7 @@ import {
   serializeSteps,
   rowToUiMessage,
   prepareAgentStep,
+  stepBudgetWarning,
   flushAssistant,
   stripNulChars,
   chatStreamMetadata,
@@ -22,7 +23,11 @@ import {
   isInterruptResume,
   sameInstant,
   MAX_AGENT_STEPS,
+  STEP_BUDGET_WARNING_LEAD,
   FINAL_STEP_INSTRUCTION,
+  FINAL_STEP_NUDGE,
+  STEP_LIMIT_NO_ANSWER_MARKER,
+  OUTPUT_DEGENERATION_ERROR,
 } from './ai-chat.service';
 import type { AiChatMessage, Workspace } from '@docmost/db/types/entity.types';
 import { buildSystemPrompt } from './ai-chat.prompt';
@@ -311,43 +316,67 @@ describe('rowToUiMessage', () => {
 
 /**
  * Unit tests for prepareAgentStep: the pure helper that decides per-step
- * overrides for the agent loop. Early steps return undefined (default
- * behavior); the final allowed step (stepNumber === MAX_AGENT_STEPS - 1) forces
- * a text-only synthesis answer (toolChoice 'none') with the FINAL_STEP_INSTRUCTION
- * appended onto — not replacing — the original system prompt.
+ * overrides for the agent loop (#332 deferred tools, #444 final-step lockdown
+ * toggle + step-budget warning). Parametrized by the two toggles so a change to
+ * one path cannot silently mask a regression in the other.
+ *
+ * Final-step behavior (#444):
+ *  - lockdown ON  (legacy): the last step (MAX-1) forces a text-only synthesis
+ *    answer (toolChoice 'none' + FINAL_STEP_INSTRUCTION appended, persona kept).
+ *  - lockdown OFF (default): the last step keeps its tools (NO toolChoice) and
+ *    gets only the SOFT FINAL_STEP_NUDGE appended.
  */
 // Narrowing helpers for the prepareAgentStep union return type.
 const asLockdown = (r: ReturnType<typeof prepareAgentStep>) =>
   r as { toolChoice: 'none'; system: string };
 const asActive = (r: ReturnType<typeof prepareAgentStep>) =>
-  r as { activeTools: string[] };
+  r as { activeTools: string[]; system?: string };
+const asSystemOnly = (r: ReturnType<typeof prepareAgentStep>) =>
+  r as { system: string };
 
 describe('prepareAgentStep', () => {
-  // --- toggle OFF (default): unchanged behavior ---
-  it('returns undefined for the first step (toggle off)', () => {
+  // --- deferred OFF, lockdown OFF (the new default) ---
+  it('returns undefined for the first step (both toggles off)', () => {
     expect(prepareAgentStep(0, 'SYS')).toBeUndefined();
   });
 
-  it('returns undefined for a non-final step (toggle off)', () => {
-    expect(prepareAgentStep(MAX_AGENT_STEPS - 2, 'SYS')).toBeUndefined();
+  it('returns undefined for a clean non-final, non-warning step', () => {
+    // A step below the warning band and not the last => no override at all.
+    expect(prepareAgentStep(MAX_AGENT_STEPS - 10, 'SYS')).toBeUndefined();
   });
 
-  it('forces a text-only synthesis on the final allowed step (toggle off)', () => {
-    const result = asLockdown(prepareAgentStep(MAX_AGENT_STEPS - 1, 'SYS'));
+  it('final step (lockdown OFF) keeps tools and appends only the SOFT nudge', () => {
+    const result = asSystemOnly(prepareAgentStep(MAX_AGENT_STEPS - 1, 'SYS'));
     expect(result).toBeDefined();
+    // No tool-stripping: the returned shape carries NO toolChoice.
+    expect(
+      (result as unknown as { toolChoice?: string }).toolChoice,
+    ).toBeUndefined();
+    expect(result.system.startsWith('SYS')).toBe(true);
+    expect(result.system).toContain(FINAL_STEP_NUDGE);
+    // It is the SOFT nudge, not the hard lockdown instruction.
+    expect(result.system).not.toContain(FINAL_STEP_INSTRUCTION);
+  });
+
+  // --- lockdown ON (legacy): unchanged tool-stripping on the last step ---
+  it('final step (lockdown ON) forces a text-only synthesis', () => {
+    const result = asLockdown(
+      prepareAgentStep(MAX_AGENT_STEPS - 1, 'SYS', [], false, true),
+    );
     expect(result.toolChoice).toBe('none');
     // The original persona is preserved (prefix), not replaced.
     expect(result.system.startsWith('SYS')).toBe(true);
-    // The synthesis instruction is appended.
+    // The synthesis instruction is appended (NOT the soft nudge).
     expect(result.system).toContain(FINAL_STEP_INSTRUCTION);
+    expect(result.system).not.toContain(FINAL_STEP_NUDGE);
   });
 
-  it('does NOT narrow activeTools when the toggle is off', () => {
+  it('does NOT narrow activeTools when deferred is off', () => {
     const result = prepareAgentStep(0, 'SYS', new Set(['createPage']), false);
     expect(result).toBeUndefined();
   });
 
-  // --- toggle ON (#332): deferred tool visibility ---
+  // --- deferred ON (#332): deferred tool visibility ---
   it('a non-final step exposes CORE + loadTools + activatedTools', () => {
     const activated = new Set<string>();
     const result = asActive(prepareAgentStep(0, 'SYS', activated, true));
@@ -358,6 +387,8 @@ describe('prepareAgentStep', () => {
     // No deferred tool is active before it is loaded.
     expect(result.activeTools).not.toContain('createPage');
     expect(result.activeTools).not.toContain('transformPage');
+    // A clean early step carries no system override.
+    expect(result.system).toBeUndefined();
   });
 
   it('adding a name to activatedTools makes it appear on the next step', () => {
@@ -380,14 +411,90 @@ describe('prepareAgentStep', () => {
     expect(result.activeTools).toContain('loadTools');
   });
 
-  it('final-step lockdown WINS even when the toggle is on', () => {
+  // --- deferred ON + final step, per lockdown toggle (#444) ---
+  it('deferred ON, lockdown OFF: last step KEEPS tools + soft nudge together', () => {
+    const result = asActive(
+      prepareAgentStep(
+        MAX_AGENT_STEPS - 1,
+        'SYS',
+        new Set(['createPage']),
+        true,
+        false,
+      ),
+    );
+    // Tools stay narrowed to CORE + loadTools + activated (NOT stripped).
+    expect(result.activeTools).toContain('editPageText');
+    expect(result.activeTools).toContain('loadTools');
+    expect(result.activeTools).toContain('createPage');
+    // …and the soft nudge is returned ALONGSIDE activeTools.
+    expect(result.system).toContain(FINAL_STEP_NUDGE);
+    expect(
+      (result as unknown as { toolChoice?: string }).toolChoice,
+    ).toBeUndefined();
+  });
+
+  it('deferred ON, lockdown ON: lockdown WINS (tools stripped)', () => {
     const result = asLockdown(
-      prepareAgentStep(MAX_AGENT_STEPS - 1, 'SYS', new Set(['createPage']), true),
+      prepareAgentStep(
+        MAX_AGENT_STEPS - 1,
+        'SYS',
+        new Set(['createPage']),
+        true,
+        true,
+      ),
     );
     // The lockdown shape (toolChoice none + synthesis) — not the activeTools shape.
     expect(result.toolChoice).toBe('none');
     expect(result.system).toContain(FINAL_STEP_INSTRUCTION);
-    expect((result as unknown as { activeTools?: string[] }).activeTools).toBeUndefined();
+    expect(
+      (result as unknown as { activeTools?: string[] }).activeTools,
+    ).toBeUndefined();
+  });
+});
+
+/**
+ * Step-budget warning boundaries (#444). At MAX_AGENT_STEPS=50 the warning fires
+ * on steps MAX-6 .. MAX-2 (44..48) with a decreasing remaining-count, is CLEAN
+ * below the band (0..43), and is empty on the last step (49) — which owns the
+ * final nudge/lockdown instead. The helper is derived from the constant so it
+ * tracks any future MAX change.
+ */
+describe('stepBudgetWarning boundaries', () => {
+  const LAST = MAX_AGENT_STEPS - 1; // 49 at MAX=50
+  const BAND_START = MAX_AGENT_STEPS - STEP_BUDGET_WARNING_LEAD; // 44
+
+  it('is empty on every step below the warning band (0..BAND_START-1)', () => {
+    for (let s = 0; s < BAND_START; s++) {
+      expect(stepBudgetWarning(s)).toBe('');
+    }
+  });
+
+  it('fires on BAND_START..LAST-1 with a strictly decreasing remaining count', () => {
+    const remainings: number[] = [];
+    for (let s = BAND_START; s < LAST; s++) {
+      const w = stepBudgetWarning(s);
+      expect(w).toContain('tool-use steps remain');
+      const m = w.match(/Only (\d+) tool-use steps remain/);
+      expect(m).not.toBeNull();
+      remainings.push(Number(m![1]));
+    }
+    // Exactly STEP_BUDGET_WARNING_LEAD-1 warning steps (44..48).
+    expect(remainings).toHaveLength(STEP_BUDGET_WARNING_LEAD - 1);
+    // Remaining = MAX-1-step, so it decreases by 1 each step and ends at 1.
+    for (let i = 1; i < remainings.length; i++) {
+      expect(remainings[i]).toBe(remainings[i - 1] - 1);
+    }
+    expect(remainings[remainings.length - 1]).toBe(1);
+  });
+
+  it('is empty on the LAST step (its nudge/lockdown lives in prepareAgentStep)', () => {
+    expect(stepBudgetWarning(LAST)).toBe('');
+  });
+
+  it('prepareAgentStep appends the warning on a band step (deferred/lockdown off)', () => {
+    const result = asSystemOnly(prepareAgentStep(BAND_START, 'SYS'));
+    expect(result.system).toContain('Stop exploring and start acting now');
+    expect(result.system).not.toContain(FINAL_STEP_NUDGE);
   });
 });
 
@@ -1341,6 +1448,7 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
       {} as never, // pageAccess
       {
         isAiChatDeferredToolsEnabled: () => false,
+        isAiChatFinalStepLockdownEnabled: () => false,
         isAiChatResumableStreamEnabled: () => opts.resumable,
       } as never,
       streamRegistry as never,
@@ -1429,3 +1537,348 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
     expect(streamRegistry.abortEntry).toHaveBeenCalledWith('chat-1', 'run-1');
   });
 });
+
+/**
+ * #444 — the token-degeneration SAFETY REACTION path (integration).
+ *
+ * output-degeneration.spec.ts proves the detector DETECTS; this proves the wired
+ * REACTION: a degenerate stream must (1) trip the detector in onChunk, (2) abort
+ * the turn via the INTERNAL degeneration controller (distinct from a user Stop),
+ * (3) truncate the runaway tail before persist in onAbort, (4) persist status
+ * 'error' with the OUTPUT_DEGENERATION_ERROR message (not a bare 'aborted' and not
+ * a swept 'streaming'), and (5) still release the leased external MCP clients.
+ *
+ * Harness: streamText is the SAME jest.fn mocked at the top of this file. Unlike
+ * the pipe-options suite above (which only inspects the pipe call), this mock
+ * CAPTURES the streamText options (onChunk/onAbort/onFinish + abortSignal) so the
+ * test can drive the callbacks exactly as the AI SDK would — feeding degenerate
+ * text-delta chunks through onChunk until the service's own AbortController fires,
+ * then invoking onAbort (which the SDK does on an aborted signal). No new mocking
+ * style is invented; it reuses the makeRes / service-construction shape above.
+ */
+describe('AiChatService.stream — token-degeneration reaction (#444)', () => {
+  const streamTextMock = streamText as unknown as jest.Mock;
+
+  beforeEach(() => {
+    streamTextMock.mockReset();
+    jest
+      .spyOn(Logger.prototype, 'log')
+      .mockImplementation(() => undefined as never);
+    jest
+      .spyOn(Logger.prototype, 'error')
+      .mockImplementation(() => undefined as never);
+    jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  function makeRes() {
+    return {
+      raw: {
+        writeHead: jest.fn(),
+        write: jest.fn(),
+        once: jest.fn(),
+        on: jest.fn(),
+        flushHeaders: jest.fn(),
+        writableEnded: false,
+        destroyed: false,
+      },
+    };
+  }
+
+  // Wire the full stream() path with in-memory fakes. The assistant row is
+  // captured so the terminal finalize (an UPDATE of the upfront-seeded row) can be
+  // asserted. One external MCP client with a close() spy lets us assert leases are
+  // released on the terminal path. lockdown OFF (default) so the detector is the
+  // active guard.
+  function makeService() {
+    // The upfront insert seeds the assistant row; findById/insert stamp a stable
+    // id so planFinalizeAssistant picks the UPDATE path.
+    let seq = 0;
+    const inserted: Array<Record<string, unknown>> = [];
+    const updated: Array<{
+      id: string;
+      workspaceId: string;
+      patch: Record<string, unknown>;
+    }> = [];
+    const aiChatRepo = {
+      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
+      insert: jest.fn(),
+    };
+    const aiChatMessageRepo = {
+      insert: jest.fn(async (row: Record<string, unknown>) => {
+        inserted.push(row);
+        return { id: row.role === 'assistant' ? 'assistant-1' : `user-${++seq}` };
+      }),
+      findAllByChat: jest.fn(async () => []),
+      update: jest.fn(
+        async (
+          id: string,
+          workspaceId: string,
+          patch: Record<string, unknown>,
+        ) => {
+          updated.push({ id, workspaceId, patch });
+          return { id };
+        },
+      ),
+    };
+    const aiSettings = { resolve: jest.fn(async () => ({})) };
+    const tools = { forUser: jest.fn(async () => ({})) };
+    const mcpClose = jest.fn(async () => undefined);
+    const mcpClients = {
+      toolsFor: jest.fn(async () => ({
+        tools: {},
+        clients: [{ close: mcpClose }],
+        outcomes: [],
+        instructions: [],
+      })),
+    };
+    const streamRegistry = { open: jest.fn(), bind: jest.fn(), abortEntry: jest.fn() };
+    const svc = new AiChatService(
+      {} as never,
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      {} as never, // aiChatPageSnapshotRepo (no open page -> never touched)
+      aiSettings as never,
+      tools as never,
+      mcpClients as never,
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo (no open page)
+      {} as never, // pageAccess
+      {
+        isAiChatDeferredToolsEnabled: () => false,
+        // lockdown OFF => the degeneration detector is the anti-babble guard.
+        isAiChatFinalStepLockdownEnabled: () => false,
+        isAiChatResumableStreamEnabled: () => false,
+      } as never,
+      streamRegistry as never,
+    );
+    return { svc, inserted, updated, mcpClose };
+  }
+
+  const body = {
+    chatId: 'chat-1',
+    messages: [
+      { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
+    ],
+  };
+
+  // Capture the streamText options so the test can drive the SDK callbacks. The
+  // returned result stub is enough for the post-streamText wiring (consumeStream +
+  // pipeUIMessageStreamToResponse are no-ops here).
+  function captureStreamText(): { opts: () => Record<string, any> } {
+    let captured: Record<string, any> | undefined;
+    streamTextMock.mockImplementation((options: Record<string, any>) => {
+      captured = options;
+      return {
+        consumeStream: jest.fn(),
+        pipeUIMessageStreamToResponse: jest.fn(),
+      };
+    });
+    return {
+      opts: () => {
+        if (!captured) throw new Error('streamText was not called');
+        return captured;
+      },
+    };
+  }
+
+  async function drive(svc: AiChatService): Promise<void> {
+    await svc.stream({
+      user: { id: 'u1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 's1',
+      body: body as never,
+      res: makeRes() as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      runHooks: undefined as never,
+    });
+  }
+
+  it('degenerate stream: detects → internal abort → onAbort truncates + records OUTPUT_DEGENERATION_ERROR; leases released', async () => {
+    const { svc, updated, mcpClose } = makeService();
+    const cap = captureStreamText();
+    await drive(svc);
+
+    const opts = cap.opts();
+    // The turn's abort signal is the UNION of the socket/run signal and the
+    // internal degeneration controller — untripped before any output.
+    expect(opts.abortSignal.aborted).toBe(false);
+
+    // Feed a runaway "loadTools.\n" loop the way the SDK streams it: many small
+    // text-delta chunks. The onChunk throttle only re-checks every ~2000 chars, so
+    // deliver well past that so the detector's identical-line rule (>=25 lines)
+    // and the ~2000-char throttle both fire.
+    const line = 'loadTools.\n';
+    let delivered = 0;
+    for (let i = 0; i < 400 && !opts.abortSignal.aborted; i++) {
+      opts.onChunk({ chunk: { type: 'text-delta', text: line } });
+      delivered += line.length;
+    }
+
+    // The detector must have tripped and aborted via the INTERNAL controller — the
+    // reason carries the degeneration message, distinguishing it from a user Stop
+    // (which aborts with no such reason) or a socket disconnect.
+    expect(opts.abortSignal.aborted).toBe(true);
+    expect(delivered).toBeGreaterThan(2000);
+    expect(String(opts.abortSignal.reason)).toContain(
+      'Output degeneration detected',
+    );
+
+    // The SDK reacts to the aborted signal by invoking onAbort. `steps` is empty
+    // (the runaway never finished a step); the in-progress runaway text is what
+    // gets truncated + persisted.
+    await opts.onAbort({ steps: [] });
+
+    // Terminal finalize = an UPDATE of the upfront-seeded assistant row (assistant
+    // row was inserted upfront, so planFinalizeAssistant -> UPDATE).
+    expect(updated).toHaveLength(1);
+    const patch = updated[0].patch as {
+      status: string;
+      content: string;
+      metadata: Record<string, unknown>;
+    };
+    // (4) status 'error' with the degeneration message — NOT 'aborted' and NOT a
+    // swept 'streaming'. This distinguishes it from a user Stop / server restart.
+    expect(patch.status).toBe('error');
+    expect(patch.metadata.error).toBe(OUTPUT_DEGENERATION_ERROR);
+    expect(patch.metadata.finishReason).toBe('error');
+    // (3) the runaway tail is TRUNCATED, not the full multi-KB babble: the marker
+    // is present and the persisted content is far shorter than what was streamed.
+    expect(patch.content).toContain('output truncated');
+    expect(patch.content.length).toBeLessThan(delivered);
+    // Only a few loop reps survive (truncateDegeneratedTail keeps a handful).
+    expect((patch.content.match(/loadTools\./g) ?? []).length).toBeLessThan(10);
+
+    // (5) the leased external MCP client is still released on this terminal path.
+    expect(mcpClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('degeneration onAbort differs from a NORMAL/user abort (no truncation, no error)', async () => {
+    // Same harness, but the stream is NOT degenerate: a clean short answer, then a
+    // user Stop reaches onAbort WITHOUT the degeneration controller having fired.
+    const { svc, updated, mcpClose } = makeService();
+    const cap = captureStreamText();
+    await drive(svc);
+    const opts = cap.opts();
+
+    opts.onChunk({ chunk: { type: 'text-delta', text: 'A normal partial answer.' } });
+    // The detector never tripped -> the union signal is NOT aborted by us.
+    expect(opts.abortSignal.aborted).toBe(false);
+
+    // A user Stop / disconnect drives onAbort with the partial (clean) text.
+    await opts.onAbort({ steps: [] });
+
+    expect(updated).toHaveLength(1);
+    const patch = updated[0].patch as {
+      status: string;
+      content: string;
+      metadata: Record<string, unknown>;
+    };
+    // A normal abort persists status 'aborted' with NO error and NO truncation
+    // marker — the branch is genuinely distinguished from the degeneration path.
+    expect(patch.status).toBe('aborted');
+    expect('error' in patch.metadata).toBe(false);
+    expect(patch.content).toBe('A normal partial answer.');
+    expect(patch.content).not.toContain('output truncated');
+    // Cleanup still runs on the normal abort path too.
+    expect(mcpClose).toHaveBeenCalledTimes(1);
+  });
+
+  /**
+   * Empty-turn marker (#444): onFinish appends STEP_LIMIT_NO_ANSWER_MARKER only
+   * when the turn burned ALL its steps (steps.length >= MAX_AGENT_STEPS) AND never
+   * produced any text. The negative: a normal turn ending WITH text is left alone.
+   */
+  it('empty turn (no text + steps exhausted) persists the STEP_LIMIT_NO_ANSWER_MARKER', async () => {
+    const { svc, updated } = makeService();
+    const cap = captureStreamText();
+    await drive(svc);
+    const opts = cap.opts();
+
+    // MAX_AGENT_STEPS text-less steps (only tool calls) => step-exhausted, no text.
+    const steps = Array.from({ length: MAX_AGENT_STEPS }, () => ({
+      text: '',
+      toolCalls: [{ toolCallId: 'c1', toolName: 'searchPages', input: {} }],
+      toolResults: [
+        { toolCallId: 'c1', toolName: 'searchPages', output: { hits: [] } },
+      ],
+    }));
+    await opts.onFinish({
+      text: '',
+      finishReason: 'tool-calls',
+      totalUsage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+      usage: { inputTokens: 1, outputTokens: 1 },
+      steps,
+    });
+
+    expect(updated).toHaveLength(1);
+    const patch = updated[0].patch as { status: string; content: string };
+    expect(patch.status).toBe('completed');
+    // The synthetic marker is the trailing text of the persisted content.
+    expect(patch.content).toContain(STEP_LIMIT_NO_ANSWER_MARKER);
+  });
+
+  it('normal turn ending WITH text does NOT get the empty-turn marker', async () => {
+    const { svc, updated } = makeService();
+    const cap = captureStreamText();
+    await drive(svc);
+    const opts = cap.opts();
+
+    // A single step that produced a real answer, well under the step cap.
+    const steps = [
+      { text: 'Here is the finished answer.', toolCalls: [], toolResults: [] },
+    ];
+    await opts.onFinish({
+      text: 'Here is the finished answer.',
+      finishReason: 'stop',
+      totalUsage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+      usage: { inputTokens: 1, outputTokens: 1 },
+      steps,
+    });
+
+    expect(updated).toHaveLength(1);
+    const patch = updated[0].patch as { status: string; content: string };
+    expect(patch.status).toBe('completed');
+    expect(patch.content).toBe('Here is the finished answer.');
+    expect(patch.content).not.toContain(STEP_LIMIT_NO_ANSWER_MARKER);
+  });
+
+  it('step-exhausted turn that DID produce text keeps the text, no marker (guards the AND)', async () => {
+    // Exhausting the step budget alone must NOT append the marker when SOME step
+    // produced text — the marker keys off "no text" too. Drive the real onFinish
+    // with MAX_AGENT_STEPS steps where the last one carries the answer.
+    const { svc, updated } = makeService();
+    const cap = captureStreamText();
+    await drive(svc);
+    const opts = cap.opts();
+
+    const steps = Array.from({ length: MAX_AGENT_STEPS }, (_, i) => ({
+      text: i === MAX_AGENT_STEPS - 1 ? 'Final synthesized answer.' : '',
+      toolCalls:
+        i === MAX_AGENT_STEPS - 1
+          ? []
+          : [{ toolCallId: `c${i}`, toolName: 'searchPages', input: {} }],
+      toolResults:
+        i === MAX_AGENT_STEPS - 1
+          ? []
+          : [{ toolCallId: `c${i}`, toolName: 'searchPages', output: {} }],
+    }));
+    await opts.onFinish({
+      text: 'Final synthesized answer.',
+      finishReason: 'stop',
+      totalUsage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+      usage: { inputTokens: 1, outputTokens: 1 },
+      steps,
+    });
+
+    expect(updated).toHaveLength(1);
+    const patch = updated[0].patch as { content: string };
+    expect(patch.content).toContain('Final synthesized answer.');
+    expect(patch.content).not.toContain(STEP_LIMIT_NO_ANSWER_MARKER);
+  });
+});

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

@@ -4,6 +4,7 @@ import {
   Injectable,
   Logger,
   OnModuleInit,
+  ServiceUnavailableException,
 } from '@nestjs/common';
 import { FastifyReply } from 'fastify';
 import {
@@ -52,11 +53,25 @@ import {
   startSseHeartbeat,
   stripStreamingHopByHopHeaders,
 } from './sse-resilience';
+import {
+  isDegenerateOutput,
+  truncateDegeneratedTail,
+  shouldCheckDegeneration,
+} from './output-degeneration';
 
 // Max agent steps per turn. One step = one model generation; a step that calls
 // tools is followed by another step carrying the tool results. Raised from 8 so
-// multi-search research questions are not cut off mid-investigation.
-const MAX_AGENT_STEPS = 20;
+// multi-search research questions are not cut off mid-investigation, then from 20
+// to 50 (#444) so read-heavy turns (e.g. dozens of searchInPage sweeps) do not
+// exhaust the budget before acting.
+const MAX_AGENT_STEPS = 50;
+
+// How many steps before the LAST one the step-budget warning starts firing
+// (#444). At MAX-STEP_BUDGET_WARNING_LEAD .. MAX-2 the model is told to stop
+// exploring and start acting, with the remaining count decreasing each step; the
+// last step (MAX-1) has its own final nudge / lockdown instead (see
+// prepareAgentStep).
+const STEP_BUDGET_WARNING_LEAD = 6;
 
 // Wall-clock ceiling for building the external MCP toolset during the per-turn
 // setup phase (before streamText owns the lifecycle). Defense-in-depth ABOVE the
@@ -82,16 +97,69 @@ const FINAL_STEP_INSTRUCTION =
   'language. If the information is incomplete, say so explicitly: summarize ' +
   'what you found, what is still missing, and give your best partial conclusion.';
 
-// Pure, unit-testable: decide per-step overrides. Two responsibilities:
-//   1. Final-step lockdown (always): on the final allowed step force a text-only
-//      synthesis answer (toolChoice 'none' + FINAL_STEP_INSTRUCTION). This WINS —
-//      it takes precedence over the deferred-tool narrowing below.
-//   2. Deferred tool visibility (#332): when `deferredEnabled` and NOT the final
-//      step, expose only the CORE tools + loadTools + whatever loadTools has
-//      activated so far this turn (`activatedTools`), via `activeTools`. Deferred
-//      tools stay in the <tool_catalog> until the model loads them.
-// When `deferredEnabled` is false the behavior is unchanged: undefined on normal
-// steps (all tools active), lockdown on the final step.
+// SOFT final-step nudge (#444), used when the final-step lockdown toggle is OFF
+// (the new default). Unlike FINAL_STEP_INSTRUCTION it does NOT strip tools
+// (toolChoice stays untouched), so the model is never forced into a tool-less
+// state mid-work — that tool-stripping is what triggered the 255KB token-loop
+// degeneration incident. It only asks the model to finish with a text summary.
+const FINAL_STEP_NUDGE =
+  'This is the LAST step of this turn. Write your final answer to the user now.\n' +
+  'You may still call tools, but the turn ends after this step either way —\n' +
+  'prefer finishing with a clear text summary of what was done and what remains.';
+
+// Synthetic marker text appended in onFinish when a step-exhausted turn produced
+// 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.
+const STEP_LIMIT_NO_ANSWER_MARKER =
+  '(Достигнут лимит шагов — итоговый ответ не сформулирован; работа могла ' +
+  'остаться незавершённой. Напишите «продолжай», чтобы агент продолжил.)';
+
+// 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)
+// and from a server restart ('streaming' -> swept to 'aborted' with no message).
+const OUTPUT_DEGENERATION_ERROR =
+  'Output degeneration detected (repeated token loop)';
+
+/**
+ * Compute the step-budget warning text (#444), or '' when this step is outside
+ * the warning band. The warning fires on steps
+ * MAX_AGENT_STEPS-STEP_BUDGET_WARNING_LEAD .. MAX_AGENT_STEPS-2 (NOT the last
+ * step, which has its own final nudge/lockdown), telling the model to stop
+ * exploring and start acting. `N` is the number of tool-use steps still
+ * remaining (`MAX_AGENT_STEPS - 1 - stepNumber`), so it decreases toward the
+ * end. Pure.
+ */
+export function stepBudgetWarning(stepNumber: number): string {
+  const isLastStep = stepNumber >= MAX_AGENT_STEPS - 1;
+  const inBand = stepNumber >= MAX_AGENT_STEPS - STEP_BUDGET_WARNING_LEAD;
+  if (isLastStep || !inBand) return '';
+  const remaining = MAX_AGENT_STEPS - 1 - stepNumber;
+  return (
+    `Only ${remaining} tool-use steps remain in this turn. Stop exploring and start acting now\n` +
+    '(make the edits / create the comments / produce results). Leave room to finish\n' +
+    'with a final text answer.'
+  );
+}
+
+// Pure, unit-testable: decide per-step overrides. Responsibilities:
+//   1. Final-step handling. Two modes, chosen by `finalStepLockdownEnabled`:
+//      - toggle ON (legacy): on the final allowed step force a text-only
+//        synthesis answer (toolChoice 'none' + FINAL_STEP_INSTRUCTION). This WINS
+//        — it takes precedence over the deferred-tool narrowing below.
+//      - toggle OFF (new default, #444): do NOT touch toolChoice — tools stay
+//        available on every step incl. the last, so the model is never stripped
+//        of its tools mid-work (the cause of the token-loop degeneration
+//        incident). A SOFT nudge (FINAL_STEP_NUDGE) is appended to `system`, and
+//        the deferred-tool `activeTools` narrowing still applies to the last step
+//        (both `activeTools` and `system` are returned together).
+//   2. Step-budget warning (#444): on steps in the warning band (but not the
+//      last, which has its own nudge/lockdown) append stepBudgetWarning(...) to
+//      `system` so the model starts acting before it runs out of steps.
+//   3. Deferred tool visibility (#332): when `deferredEnabled`, expose only the
+//      CORE tools + loadTools + whatever loadTools has activated so far this turn
+//      (`activatedTools`), via `activeTools`. Deferred tools stay in the
+//      <tool_catalog> until the model loads them.
 //
 // `system` is the in-scope system prompt; we CONCATENATE so the original
 // persona/context is preserved — a bare `system` override would REPLACE the
@@ -107,31 +175,53 @@ export function prepareAgentStep(
   system: string,
   activatedTools: ReadonlySet<string> | readonly string[] = [],
   deferredEnabled = false,
+  finalStepLockdownEnabled = false,
 ):
   | { toolChoice: 'none'; system: string }
-  | { activeTools: string[] }
+  | { activeTools: string[]; system?: string }
+  | { system: string }
   | undefined {
-  // Final-step lockdown WINS (applies regardless of the deferred toggle).
-  if (stepNumber >= MAX_AGENT_STEPS - 1) {
+  const isLastStep = stepNumber >= MAX_AGENT_STEPS - 1;
+
+  // Legacy final-step lockdown (toggle ON): text-only synthesis. WINS over the
+  // deferred narrowing AND drops tools for this step.
+  if (isLastStep && finalStepLockdownEnabled) {
     return {
       toolChoice: 'none',
       system: `${system}\n\n${FINAL_STEP_INSTRUCTION}`,
     };
   }
-  // Deferred tool loading: narrow this step's visible tools to CORE + loadTools
-  // + the tools already activated this turn.
+
+  // Compute the extra system text for this step: the soft final nudge on the last
+  // step (toggle OFF), or the step-budget warning in the warning band. At most one
+  // of these applies (stepBudgetWarning returns '' on the last step).
+  const extra = isLastStep ? FINAL_STEP_NUDGE : stepBudgetWarning(stepNumber);
+  const systemForStep = extra ? `${system}\n\n${extra}` : undefined;
+
+  // Deferred tool loading: narrow this step's visible tools to CORE + loadTools +
+  // the tools already activated this turn. Applies on EVERY step incl. the last
+  // (toggle OFF), so the model keeps its core tools available while being nudged
+  // to finish. Return `system` alongside `activeTools` when we have extra text.
   if (deferredEnabled) {
     const activated = Array.isArray(activatedTools)
       ? activatedTools
       : [...activatedTools];
-    return {
-      activeTools: [...CORE_TOOL_KEYS, LOAD_TOOLS_NAME, ...activated],
-    };
+    const activeTools = [...CORE_TOOL_KEYS, LOAD_TOOLS_NAME, ...activated];
+    return systemForStep ? { activeTools, system: systemForStep } : { activeTools };
   }
-  return undefined;
+
+  // Deferred OFF: all tools stay active; only append the extra system text (if any).
+  return systemForStep ? { system: systemForStep } : undefined;
 }
 
-export { MAX_AGENT_STEPS, FINAL_STEP_INSTRUCTION };
+export {
+  MAX_AGENT_STEPS,
+  STEP_BUDGET_WARNING_LEAD,
+  FINAL_STEP_INSTRUCTION,
+  FINAL_STEP_NUDGE,
+  STEP_LIMIT_NO_ANSWER_MARKER,
+  OUTPUT_DEGENERATION_ERROR,
+};
 
 // Pure, unit-testable post-processing for a model-generated title (#199): trim
 // whitespace, strip a single pair of surrounding quotes the model often adds,
@@ -709,12 +799,32 @@ export class AiChatService implements OnModuleInit {
             code: 'A_RUN_ALREADY_ACTIVE',
           });
         }
-        // Any OTHER run-start failure must not break the turn — fall back to the
-        // socket signal (legacy behavior) and stream anyway.
+        // Any OTHER run-start failure (e.g. a DB-pool blip) must FAIL THE TURN,
+        // not silently stream without a run-row. The old fallback let the turn
+        // continue untracked: in autonomous mode nobody could then abort it —
+        // /stop can't see a run that doesn't exist, a client disconnect doesn't
+        // abort it, and the one-run-per-chat gate would let a SECOND run in. That
+        // is an unstoppable, invisible run until process restart. Reject NOW,
+        // BEFORE the first byte (nothing is written yet, no user row inserted, no
+        // MCP lease taken), so the controller's post-hijack catch turns this
+        // HttpException into an honest 503 on the raw socket. Same policy for BOTH
+        // modes — #487 inherits it (no mode-branching here).
         this.logger.error(
-          `Failed to begin agent run (chat ${chatId}); streaming without run tracking`,
+          `Failed to begin agent run (chat ${chatId}); failing the turn`,
           err as Error,
         );
+        throw new ServiceUnavailableException({
+          message:
+            'Could not start the agent run. This is usually temporary — please try again.',
+          code: 'A_RUN_BEGIN_FAILED',
+          // Self-describe the status in the body: the controller's post-hijack
+          // catch writes getResponse() verbatim onto the raw socket, and an
+          // object-arg HttpException does NOT inject statusCode. Without it the
+          // client's 503 classifier (which reads the body JSON) could not see the
+          // status. With it present, the client's A_RUN_BEGIN_FAILED branch (which
+          // runs strictly before the generic-503 branch) shows "temporary, retry".
+          statusCode: 503,
+        });
       }
     }
 
@@ -890,6 +1000,12 @@ export class AiChatService implements OnModuleInit {
       // tools (fat/rare in-app tools + ALL external MCP tools) load on demand. When
       // OFF, every tool is active and nothing below changes.
       const deferredEnabled = this.environment.isAiChatDeferredToolsEnabled();
+      // Final-step lockdown toggle (#444). Default OFF: the last step keeps its
+      // tools and gets only a soft nudge (prepareAgentStep), and the token-
+      // degeneration detector (onChunk below) is the anti-babble guard. ON =
+      // legacy tool-stripping lockdown on the last step.
+      const finalStepLockdownEnabled =
+        this.environment.isAiChatFinalStepLockdownEnabled();
 
       let system: string;
       let docmostTools: Awaited<ReturnType<AiChatToolsService['forUser']>>;
@@ -978,6 +1094,15 @@ export class AiChatService implements OnModuleInit {
       const capturedSteps: StepLike[] = [];
       let inProgressText = '';
 
+      // 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
+      // detector runs on `inProgressText` in onChunk, throttled by growth so the
+      // pure rules only fire every ~DEGENERATION_CHECK_STEP bytes.
+      const degenerationController = new AbortController();
+      let degenerationDetected = false;
+      let lastDegenerationCheckLen = 0;
+
       // Step-granular durability (#183): create the assistant row UPFRONT in the
       // 'streaming' state (before any token), then UPDATE it as each step finishes
       // and finalize it once on the terminal callback. If the process dies
@@ -1118,11 +1243,21 @@ export class AiChatService implements OnModuleInit {
           // further tool calls and appends a synthesis instruction on that step,
           // concatenated onto the original `system` so the persona is preserved.
           prepareStep: ({ stepNumber }) =>
-            prepareAgentStep(stepNumber, system, activatedTools, deferredEnabled),
+            prepareAgentStep(
+              stepNumber,
+              system,
+              activatedTools,
+              deferredEnabled,
+              finalStepLockdownEnabled,
+            ),
           // #184: the RUN's signal (explicit-stop) when a run wraps this turn, else
           // the socket-bound signal (legacy). A browser disconnect aborts only in
-          // the legacy path.
-          abortSignal: effectiveSignal,
+          // the legacy path. #444: UNION it with the internal degeneration signal
+          // so a detected token-loop aborts the run too (AbortSignal.any — Node 20.3+).
+          abortSignal: AbortSignal.any([
+            effectiveSignal,
+            degenerationController.signal,
+          ]),
           onChunk: ({ chunk }) => {
             // DIAGNOSTIC (Safari stream-drop investigation) — temporary. Any model
             // output chunk means the stream is actively emitting bytes; track first
@@ -1132,13 +1267,44 @@ export class AiChatService implements OnModuleInit {
             lastModelChunkAt = now;
             // 'text-delta' is the assistant's prose; tool-call args are separate chunk
             // types — so this mirrors exactly what streams to the client.
-            if (chunk.type === 'text-delta') inProgressText += chunk.text;
+            if (chunk.type === 'text-delta') {
+              inProgressText += chunk.text;
+              // Token-degeneration guard (#444). Throttled: only re-run the pure
+              // rules once the text has grown ~DEGENERATION_CHECK_STEP bytes since
+              // the last check, so the tail heuristics cost is amortized. On a
+              // trigger, abort the run ONCE with a distinguishable reason.
+              if (
+                !degenerationDetected &&
+                shouldCheckDegeneration(
+                  inProgressText.length,
+                  lastDegenerationCheckLen,
+                )
+              ) {
+                lastDegenerationCheckLen = inProgressText.length;
+                if (isDegenerateOutput(inProgressText)) {
+                  degenerationDetected = true;
+                  this.logger.warn(
+                    `AI chat stream aborted (chat ${chatId}): ${OUTPUT_DEGENERATION_ERROR}`,
+                  );
+                  degenerationController.abort(
+                    new Error(OUTPUT_DEGENERATION_ERROR),
+                  );
+                }
+              }
+            }
           },
           onStepFinish: (step) => {
             // The finished step's full text is now in `step.text`; fold it in and reset
             // the in-progress accumulator for the next step.
             capturedSteps.push(step as StepLike);
             inProgressText = '';
+            // Reset the degeneration-check watermark too (#486): it tracks a byte
+            // offset INTO inProgressText, so once that resets to '' a stale (large)
+            // mark makes `inProgressText.length - lastDegenerationCheckLen` go
+            // negative and the throttled detector stays silent until a later step's
+            // text re-grows past the old offset — a whole degenerate step could slip
+            // through undetected. Zeroing it re-arms the check from the next byte.
+            lastDegenerationCheckLen = 0;
             // Step-granular durability (#183): persist this finished step (its text +
             // tool calls + tool RESULTS) the moment it ends, so a process death after
             // this point still recovers the step. Not awaited here (never block the
@@ -1174,8 +1340,22 @@ export class AiChatService implements OnModuleInit {
             // plain-text projection (full-text search / fallback). A multi-step
             // turn's `content` therefore now holds all steps' prose, not just the
             // last block.
+            // Empty-turn mitigation (#444, toggle OFF). If the turn burned all its
+            // steps WITHOUT ever producing text (every step's text is empty) and
+            // the model stopped because it hit the step cap, there is no answer to
+            // show — the lockdown used to force one. Append a synthetic marker as
+            // the trailing text so the exhausted-without-answer state is explicit
+            // to the user and, on replay, to the model next turn. `flushAssistant`
+            // takes this as the `inProgressText` trailing text arg (empty here
+            // otherwise). `stepCountIs(MAX_AGENT_STEPS)` surfaces as
+            // finishReason === 'tool-calls' (or a length/other cap), so we key off
+            // "no text produced" rather than a single finishReason string.
+            const producedText = (steps as StepLike[]).some((s) => s.text?.trim());
+            const stepExhausted = steps.length >= MAX_AGENT_STEPS;
+            const emptyTurnMarker =
+              !producedText && stepExhausted ? STEP_LIMIT_NO_ANSWER_MARKER : '';
             await finalizeAssistant(
-              flushAssistant(steps as StepLike[], '', 'completed', {
+              flushAssistant(steps as StepLike[], emptyTurnMarker, 'completed', {
                 finishReason: finishReason as string,
                 usage: totalUsage as StreamUsage,
                 contextTokens:
@@ -1252,6 +1432,30 @@ export class AiChatService implements OnModuleInit {
             await snapshotTurnEnd();
           },
           onAbort: async ({ steps }) => {
+            // #444: distinguish a degeneration abort (our internal controller) from
+            // a user Stop / disconnect. On degeneration we truncate the runaway tail
+            // before persist (so hundreds of KB of garbage never reach the DB /
+            // replay) and record it as an ERROR with a clear, distinguishable reason
+            // — NOT a bare 'aborted' (a user Stop) and NOT a swept 'streaming' (a
+            // server restart).
+            if (degenerationDetected) {
+              const truncated = truncateDegeneratedTail(inProgressText);
+              await finalizeAssistant(
+                flushAssistant(capturedSteps, truncated, 'error', {
+                  error: OUTPUT_DEGENERATION_ERROR,
+                  pageChanged,
+                }),
+              );
+              if (runId)
+                await runHooks?.onSettled?.(
+                  runId,
+                  'error',
+                  OUTPUT_DEGENERATION_ERROR,
+                );
+              await closeExternalClients();
+              await snapshotTurnEnd();
+              return;
+            }
             const partialChars =
               capturedSteps.reduce((n, s) => n + (s.text?.length ?? 0), 0) +
               inProgressText.length;

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

@@ -75,7 +75,7 @@ const LABELS: Record<
       searchPages: 'Searched pages',
       getPage: 'Read page',
       createPage: 'Created page',
-      updatePageContent: 'Updated page',
+      updatePageMarkdown: 'Updated page',
       renamePage: 'Renamed page',
       movePage: 'Moved page',
       deletePage: 'Deleted page (to trash)',
@@ -96,7 +96,7 @@ const LABELS: Record<
       searchPages: 'Искал по страницам',
       getPage: 'Прочитал страницу',
       createPage: 'Создал страницу',
-      updatePageContent: 'Обновил страницу',
+      updatePageMarkdown: 'Обновил страницу',
       renamePage: 'Переименовал страницу',
       movePage: 'Переместил страницу',
       deletePage: 'Удалил страницу (в корзину)',

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

@@ -0,0 +1,380 @@
+import { Logger } from '@nestjs/common';
+import { streamText } from 'ai';
+import {
+  hasRepeatedLineRun,
+  hasPeriodicTail,
+  isDegenerateOutput,
+  truncateDegeneratedTail,
+  shouldCheckDegeneration,
+  DEGENERATION_CHECK_STEP,
+  REPEATED_LINES_THRESHOLD,
+  MIN_PERIOD_REPEATS,
+} from './output-degeneration';
+import { AiChatService } from './ai-chat.service';
+
+// 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.
+jest.mock('ai', () => {
+  const actual = jest.requireActual('ai');
+  return { ...actual, streamText: jest.fn() };
+});
+
+/**
+ * Unit tests for the token-degeneration detector (#444) — the sole anti-babble
+ * guard once the final-step lockdown is OFF. The two rules must fire on real
+ * degeneration (the "loadTools." incident, a no-newline repeat) and MUST NOT fire
+ * on legitimate long output (edit lists, tables, code).
+ */
+describe('hasRepeatedLineRun (rule 1: identical-line run)', () => {
+  it('POSITIVE: fires on "loadTools.\\n" repeated many times (the incident)', () => {
+    const text = 'Here is my plan.\n' + 'loadTools.\n'.repeat(300);
+    expect(hasRepeatedLineRun(text)).toBe(true);
+    expect(isDegenerateOutput(text)).toBe(true);
+  });
+
+  it('POSITIVE: fires at exactly the threshold', () => {
+    const text = 'x\n'.repeat(REPEATED_LINES_THRESHOLD);
+    expect(hasRepeatedLineRun(text)).toBe(true);
+  });
+
+  it('NEGATIVE: does NOT fire just below the threshold', () => {
+    // threshold-1 identical lines followed by a distinct line.
+    const text = 'x\n'.repeat(REPEATED_LINES_THRESHOLD - 1) + 'done\n';
+    expect(hasRepeatedLineRun(text)).toBe(false);
+  });
+
+  it('NEGATIVE: a long edit list of DISTINCT lines never trips', () => {
+    const lines: string[] = [];
+    for (let i = 0; i < 200; i++) lines.push(`- edited section ${i}: fixed typo`);
+    const text = lines.join('\n');
+    expect(hasRepeatedLineRun(text)).toBe(false);
+    expect(isDegenerateOutput(text)).toBe(false);
+  });
+
+  it('NEGATIVE: a markdown table with blank separators does not trip', () => {
+    // Repeated identical rows are unusual, but blank lines break any run.
+    const block = ['| a | b |', '| - | - |', '', '| a | b |', ''];
+    const text = Array.from({ length: 60 }, () => block.join('\n')).join('\n');
+    expect(hasRepeatedLineRun(text)).toBe(false);
+  });
+
+  it('NEGATIVE: blank lines do NOT count toward a run', () => {
+    const text = '\n'.repeat(100);
+    expect(hasRepeatedLineRun(text)).toBe(false);
+  });
+});
+
+describe('hasPeriodicTail (rule 2: no-newline suffix periodicity)', () => {
+  it('POSITIVE: fires on a single char repeated with no newlines', () => {
+    const text = 'answer: ' + 'a'.repeat(500);
+    expect(hasPeriodicTail(text)).toBe(true);
+    expect(isDegenerateOutput(text)).toBe(true);
+  });
+
+  it('POSITIVE: fires on a multi-char block repeat with no newlines', () => {
+    const text = 'prefix ' + 'abcdef'.repeat(100);
+    expect(hasPeriodicTail(text)).toBe(true);
+  });
+
+  it('POSITIVE: at least MIN_PERIOD_REPEATS repeats of a small block', () => {
+    const text = 'go'.repeat(MIN_PERIOD_REPEATS);
+    expect(hasPeriodicTail(text)).toBe(true);
+  });
+
+  it('NEGATIVE: prose does not look periodic', () => {
+    const text =
+      'The quick brown fox jumps over the lazy dog while the sun sets slowly ' +
+      'behind the distant mountains and the river winds through the valley below.';
+    expect(hasPeriodicTail(text)).toBe(false);
+    expect(isDegenerateOutput(text)).toBe(false);
+  });
+
+  it('NEGATIVE: a long code block is not flagged', () => {
+    const code = `
+function compute(values) {
+  let total = 0;
+  for (const v of values) {
+    total += v * 2;
+  }
+  return total / values.length;
+}
+export const helper = (x) => x + 1;
+const config = { retries: 3, timeout: 5000, backoff: 'exp' };
+`.repeat(3);
+    expect(isDegenerateOutput(code)).toBe(false);
+  });
+
+  it('NEGATIVE: a short string well under the repeat count is safe', () => {
+    expect(hasPeriodicTail('ababab')).toBe(false);
+  });
+
+  // Regression (#444): a trivial single-char period (p===1) must NOT flag
+  // legitimate divider/underline/whitespace runs. These are common in real
+  // model output and previously false-positived at ~20 identical chars, aborting
+  // the run and truncating output. They must all be treated as clean.
+  it('NEGATIVE: a markdown horizontal rule is not flagged', () => {
+    const text = 'text\n' + '-'.repeat(40);
+    expect(hasPeriodicTail(text)).toBe(false);
+    expect(isDegenerateOutput(text)).toBe(false);
+  });
+
+  it('NEGATIVE: a setext heading underline is not flagged', () => {
+    const text = 'Title\n' + '='.repeat(30);
+    expect(hasPeriodicTail(text)).toBe(false);
+    expect(isDegenerateOutput(text)).toBe(false);
+  });
+
+  it('NEGATIVE: a box-drawing divider with no trailing newline is not flagged', () => {
+    const text = 'done ' + '─'.repeat(50);
+    expect(hasPeriodicTail(text)).toBe(false);
+    expect(isDegenerateOutput(text)).toBe(false);
+  });
+
+  it('NEGATIVE: trailing spaces are not flagged', () => {
+    const text = 'answer' + ' '.repeat(40);
+    expect(hasPeriodicTail(text)).toBe(false);
+    expect(isDegenerateOutput(text)).toBe(false);
+  });
+
+  // TRIVIAL_MIN_REPEATS boundary (#444 review). The monochar-tail branch fires at
+  // EXACTLY 60 identical trailing chars (`run >= TRIVIAL_MIN_REPEATS`), so 59 is
+  // clean and 60 trips. These pin the `>=` and MUST fail if the comparison is
+  // flipped to `>` (the surviving mutation). The value 60 is HARD-CODED here on
+  // purpose: TRIVIAL_MIN_REPEATS is a private constant and the assert must lock
+  // the literal boundary the reviewer named, not track a constant edit.
+  it('NEGATIVE: 59 identical trailing chars is one below the monochar threshold', () => {
+    expect(hasPeriodicTail('x'.repeat(59))).toBe(false);
+    expect(isDegenerateOutput('x'.repeat(59))).toBe(false);
+  });
+
+  it('POSITIVE: 60 identical trailing chars hits the monochar threshold exactly', () => {
+    // Fails if `run >= TRIVIAL_MIN_REPEATS` is mutated to `run > …`.
+    expect(hasPeriodicTail('x'.repeat(60))).toBe(true);
+    expect(isDegenerateOutput('x'.repeat(60))).toBe(true);
+  });
+
+  // Positive counterparts: a GENUINE single-char runaway (hundreds+ of repeats)
+  // and the real incident (period>=2, "loadTools." ×N) must still fire.
+  it('POSITIVE: a genuine single-char runaway is still flagged', () => {
+    const text = 'x'.repeat(5000);
+    expect(hasPeriodicTail(text)).toBe(true);
+    expect(isDegenerateOutput(text)).toBe(true);
+  });
+
+  it('POSITIVE: the "loadTools." incident (period>=2) is still flagged', () => {
+    const text = 'loadTools.'.repeat(500);
+    expect(hasPeriodicTail(text)).toBe(true);
+    expect(isDegenerateOutput(text)).toBe(true);
+  });
+});
+
+describe('truncateDegeneratedTail', () => {
+  it('collapses a repeated-line loop to a few reps + marker', () => {
+    const text = 'plan\n' + 'loadTools.\n'.repeat(20000);
+    const out = truncateDegeneratedTail(text);
+    expect(out.length).toBeLessThan(text.length);
+    expect(out).toContain('output truncated');
+    // Keeps the leading context and a few loop reps.
+    expect(out).toContain('plan');
+    expect((out.match(/loadTools\./g) ?? []).length).toBeLessThan(10);
+  });
+
+  it('collapses a no-newline periodic loop to a few blocks + marker', () => {
+    const text = 'answer: ' + 'xy'.repeat(50000);
+    const out = truncateDegeneratedTail(text);
+    expect(out.length).toBeLessThan(text.length);
+    expect(out).toContain('output truncated');
+    expect(out).toContain('answer:');
+  });
+
+  it('returns non-degenerate text unchanged (by identity)', () => {
+    const text = 'A perfectly normal, finished assistant answer.';
+    expect(truncateDegeneratedTail(text)).toBe(text);
+  });
+});
+
+/**
+ * Throttle + step-boundary reset (#486). The stream keeps a watermark
+ * (`lastDegenerationCheckLen`) that is an OFFSET into the accumulated step text.
+ * On a step boundary the accumulator resets to '', so the watermark MUST reset to
+ * 0 too — otherwise the throttle goes silent for the whole next step. These tests
+ * pin the pure decision AND the reset property that ai-chat.service.onStepFinish
+ * now enforces.
+ */
+describe('shouldCheckDegeneration (throttle) + step-boundary reset (#486)', () => {
+  it('fires once the text grows a full DEGENERATION_CHECK_STEP past the mark', () => {
+    expect(shouldCheckDegeneration(DEGENERATION_CHECK_STEP, 0)).toBe(true);
+    expect(shouldCheckDegeneration(DEGENERATION_CHECK_STEP - 1, 0)).toBe(false);
+    expect(shouldCheckDegeneration(5000, 3000)).toBe(true); // grew 2000 since mark
+    expect(shouldCheckDegeneration(4000, 3000)).toBe(false); // grew only 1000
+  });
+
+  it('BUG (no reset): a stale large watermark silences the next step', () => {
+    // End of a long step: the watermark sits at 5000. The step ends and the
+    // accumulator resets to '' — but if the watermark is NOT reset, a fresh short
+    // degenerate burst (length 2000) never triggers a check: 2000 - 5000 < STEP.
+    const staleWatermark = 5000;
+    const nextStepLen = DEGENERATION_CHECK_STEP; // a fresh 2KB burst
+    expect(shouldCheckDegeneration(nextStepLen, staleWatermark)).toBe(false);
+  });
+
+  it('FIX (reset to 0): the same short degenerate burst IS checked and detected', () => {
+    // onStepFinish now zeroes the watermark, so the fresh burst re-arms the check.
+    const resetWatermark = 0;
+    const degenerateBurst = 'loadTools.\n'.repeat(300); // real degeneration
+    expect(degenerateBurst.length).toBeGreaterThanOrEqual(DEGENERATION_CHECK_STEP);
+    // The throttle now fires...
+    expect(
+      shouldCheckDegeneration(degenerateBurst.length, resetWatermark),
+    ).toBe(true);
+    // ...and the detector catches the loop that would otherwise stream unchecked.
+    expect(isDegenerateOutput(degenerateBurst)).toBe(true);
+  });
+});
+
+/**
+ * BEHAVIOR guard for the ACTUAL fix (#486, ai-chat.service.onStepFinish resets
+ * lastDegenerationCheckLen to 0). The pure tests above use a hard-coded
+ * resetWatermark, so a REVERT of the real `lastDegenerationCheckLen = 0` line
+ * would not redden any of them. This drives the REAL onChunk/onStepFinish
+ * closures from stream() end to end and asserts the run is aborted when a fresh
+ * degenerate burst arrives in the step AFTER a long clean step — which only
+ * happens if the watermark was actually zeroed on the step boundary.
+ */
+describe('AiChatService: onStepFinish re-arms the degeneration watermark (#486)', () => {
+  const streamTextMock = streamText as unknown as jest.Mock;
+
+  function makeRes() {
+    return {
+      raw: {
+        writeHead: jest.fn(),
+        write: jest.fn(),
+        once: jest.fn(),
+        on: jest.fn(),
+        flushHeaders: jest.fn(),
+        writableEnded: false,
+        destroyed: false,
+      },
+    };
+  }
+
+  function makeService() {
+    const aiChatRepo = {
+      findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
+      insert: jest.fn(),
+    };
+    const aiChatMessageRepo = {
+      insert: jest.fn(async () => ({ id: 'msg-1' })),
+      findAllByChat: jest.fn(async () => []),
+      update: jest.fn(async () => ({ id: 'msg-1' })),
+    };
+    const aiSettings = { resolve: jest.fn(async () => ({})) };
+    const tools = { forUser: jest.fn(async () => ({})) };
+    const mcpClients = {
+      toolsFor: jest.fn(async () => ({
+        tools: {},
+        clients: [],
+        outcomes: [],
+        instructions: [],
+      })),
+    };
+    return new AiChatService(
+      {} as never, // ai
+      aiChatRepo as never,
+      aiChatMessageRepo as never,
+      {} as never, // aiChatPageSnapshotRepo
+      aiSettings as never,
+      tools as never,
+      mcpClients as never,
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo
+      {} as never, // pageAccess
+      {
+        isAiChatDeferredToolsEnabled: () => false,
+        // Lockdown OFF -> the degeneration guard is the active anti-babble path.
+        isAiChatFinalStepLockdownEnabled: () => false,
+      } as never, // environment
+    );
+  }
+
+  beforeEach(() => {
+    streamTextMock.mockReset();
+    jest.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined as never);
+    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('aborts on a fresh degenerate burst in the NEXT step (reverting the reset line reddens this)', async () => {
+    let captured:
+      | {
+          onChunk?: (e: { chunk: { type: string; text: string } }) => void;
+          onStepFinish?: (step: unknown) => void;
+          abortSignal?: AbortSignal;
+        }
+      | undefined;
+    streamTextMock.mockImplementation((opts: never) => {
+      captured = opts;
+      return {
+        consumeStream: jest.fn(),
+        pipeUIMessageStreamToResponse: jest.fn(),
+      };
+    });
+
+    const svc = makeService();
+    await svc.stream({
+      user: { id: 'user-1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 'sess-1',
+      body: {
+        chatId: 'chat-1',
+        messages: [
+          { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'hi' }] },
+        ],
+      } as never,
+      res: makeRes() as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      // No runHooks -> legacy path (socket signal), degeneration guard active.
+    });
+
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+    const onChunk = captured!.onChunk!;
+    const onStepFinish = captured!.onStepFinish!;
+    const abortSignal = captured!.abortSignal!;
+    expect(abortSignal.aborted).toBe(false);
+
+    // STEP 1: a LONG, non-degenerate first step. Distinct lines never trip the
+    // detector, but they advance the throttle watermark far past the burst size
+    // that follows (to ~5x the step). This is the stale watermark that, WITHOUT
+    // the reset, would silence step 2.
+    let counter = 0;
+    let accumulated = 0;
+    while (accumulated < DEGENERATION_CHECK_STEP * 5) {
+      const line = `unique clean line number ${counter++} with distinct words\n`;
+      accumulated += line.length;
+      onChunk({ chunk: { type: 'text-delta', text: line } });
+    }
+    expect(abortSignal.aborted).toBe(false); // clean step must not abort
+
+    // STEP BOUNDARY: the real onStepFinish resets inProgressText AND (the fix)
+    // zeroes lastDegenerationCheckLen.
+    onStepFinish({ text: 'a clean first step', toolCalls: [], toolResults: [] });
+
+    // STEP 2: a FRESH, short degenerate burst (~3.3KB). Its length is far below
+    // the step-1 stale watermark (~10KB), so WITHOUT the reset the throttle stays
+    // silent and this streams unchecked. WITH the reset (watermark 0) it re-arms,
+    // the detector fires, and the run aborts.
+    const burst = 'loadTools.\n'.repeat(300);
+    expect(burst.length).toBeGreaterThanOrEqual(DEGENERATION_CHECK_STEP);
+    expect(burst.length).toBeLessThan(DEGENERATION_CHECK_STEP * 5);
+    onChunk({ chunk: { type: 'text-delta', text: burst } });
+
+    // The decisive assertion: the composed abortSignal (unioned with the
+    // degeneration controller) is now aborted. Reverting `lastDegenerationCheckLen
+    // = 0` in onStepFinish makes this stay false.
+    expect(abortSignal.aborted).toBe(true);
+  });
+});

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

@@ -0,0 +1,215 @@
+/**
+ * Token-degeneration detector for the in-app agent stream (#444).
+ *
+ * When the final-step lockdown is OFF (the new default) there is no toolChoice
+ * override to strip the model's tools mid-work, so the anti-babble safety net is
+ * this detector. It watches the accumulating assistant text and, on a runaway
+ * repetition loop (the 255KB "loadTools." incident), aborts the run.
+ *
+ * Both rules are PURE functions of the text tail so they are cheap to run every
+ * few KB and are unit-testable in isolation. They operate on the TAIL only
+ * (`TAIL_WINDOW` chars) so the cost is bounded regardless of how long the turn is.
+ */
+
+/** How many trailing chars of the accumulated text the rules inspect. */
+export const TAIL_WINDOW = 3000;
+
+/** Rule 1 threshold: minimum consecutive identical non-empty lines to trigger. */
+export const REPEATED_LINES_THRESHOLD = 25;
+
+/** Rule 2: maximum length of a repeating block considered for periodicity. */
+export const MAX_PERIOD_LEN = 150;
+
+/** Rule 2: minimum number of consecutive block repeats to trigger. */
+export const MIN_PERIOD_REPEATS = 20;
+
+/**
+ * Rule 1 — ≥`REPEATED_LINES_THRESHOLD` consecutive IDENTICAL non-empty lines at
+ * the tail. Catches the classic newline-delimited loop ("loadTools.\n" ×N).
+ * Blank lines break a run (a table / list with blank separators never trips it);
+ * a run of ordinary distinct lines (an edit list, code) never reaches the count.
+ *
+ * NB: `REPEATED_LINES_THRESHOLD` (25) is only THIS rule's own trigger, not the
+ * effective floor for detecting a repeated-line loop. In practice a newline-
+ * delimited repeat also has a fixed period (line + '\n'), so rule 2 catches it
+ * via periodicity at `MIN_PERIOD_REPEATS` (20) repeats — the two rules combine
+ * (see `isDegenerateOutput`), so the effective lower bound for a short identical
+ * line loop is ~20, not 25. Pure.
+ */
+export function hasRepeatedLineRun(
+  text: string,
+  threshold = REPEATED_LINES_THRESHOLD,
+): boolean {
+  const tail = text.length > TAIL_WINDOW ? text.slice(-TAIL_WINDOW) : text;
+  const lines = tail.split('\n');
+  let run = 1;
+  let prev: string | null = null;
+  for (const line of lines) {
+    if (line.length > 0 && line === prev) {
+      run += 1;
+      if (run >= threshold) return true;
+    } else {
+      run = 1;
+    }
+    prev = line;
+  }
+  return false;
+}
+
+/**
+ * Rule 2 — cheap suffix-periodicity check: the tail ends in
+ * ≥`MIN_PERIOD_REPEATS` back-to-back repeats of a single block of length
+ * ≤`MAX_PERIOD_LEN`. Catches a no-newline repeat ("abcabcabc…") the line rule
+ * misses. For each candidate period length p we verify the last `repeats*p`
+ * chars are p-periodic; we stop at the smallest p that satisfies the repeat
+ * count. Bounded by MAX_PERIOD_LEN × TAIL_WINDOW comparisons — negligible. Pure.
+ */
+export function hasPeriodicTail(
+  text: string,
+  maxPeriod = MAX_PERIOD_LEN,
+  minRepeats = MIN_PERIOD_REPEATS,
+): boolean {
+  const tail = text.length > TAIL_WINDOW ? text.slice(-TAIL_WINDOW) : text;
+  const n = tail.length;
+  // Not even the shortest possible loop fits in the tail.
+  if (n < minRepeats) return false;
+  // A tail of ONE repeated char (a "trivial period") is common in LEGIT output —
+  // markdown rules (----/====), setext underlines, box-drawing dividers,
+  // trailing spaces routinely produce 20–50 identical chars. Such a run is
+  // p-periodic for EVERY p, so it would otherwise trip the block rule at p>=2
+  // too, not just p===1. We therefore split the check: a monochar tail needs far
+  // more repeats (a real single-char babble loop produces hundreds-to-thousands;
+  // 60 is well above any realistic divider yet a fifth of TAIL_WINDOW), while a
+  // genuine multi-char block repeat (>=2 distinct chars, e.g. the "loadTools."
+  // incident, period ~10) keeps the normal MIN_PERIOD_REPEATS threshold.
+  const TRIVIAL_MIN_REPEATS = 60;
+
+  // Monochar-tail check (the trivial-period case): count the trailing run of one
+  // identical char and require TRIVIAL_MIN_REPEATS of them.
+  {
+    const last = tail[n - 1];
+    let run = 1;
+    for (let i = n - 2; i >= 0 && tail[i] === last; i--) run++;
+    if (run >= TRIVIAL_MIN_REPEATS) return true;
+  }
+
+  const maxP = maxPeriod;
+  for (let p = 2; p <= maxP; p++) {
+    // Verify the last (minRepeats*p) chars are p-periodic AND not monochar (a
+    // monochar span is the trivial case handled above, so skip it here to avoid
+    // re-flagging a legit divider at a composite period).
+    const span = minRepeats * p;
+    // Not enough tail to hold this many repeats of this period.
+    if (span > n) continue;
+    const start = n - span;
+    let periodic = true;
+    let multiChar = false;
+    for (let i = n - 1; i >= start + p; i--) {
+      if (tail[i] !== tail[i - p]) {
+        periodic = false;
+        break;
+      }
+    }
+    if (!periodic) continue;
+    // Confirm the block itself has >=2 distinct chars (else it's monochar).
+    for (let i = start + 1; i < n; i++) {
+      if (tail[i] !== tail[start]) {
+        multiChar = true;
+        break;
+      }
+    }
+    if (multiChar) return true;
+  }
+  return false;
+}
+
+/**
+ * Combined guard used by the stream's onChunk: true when EITHER rule fires.
+ * Pure — the caller owns the abort side effect.
+ */
+export function isDegenerateOutput(text: string): boolean {
+  return hasRepeatedLineRun(text) || hasPeriodicTail(text);
+}
+
+/**
+ * How many bytes the in-progress text must grow before the (amortized) tail
+ * heuristics are re-run. Shared with ai-chat.service so the throttle the stream
+ * applies is the SAME one the unit test drives.
+ */
+export const DEGENERATION_CHECK_STEP = 2000;
+
+/**
+ * Throttle decision for the degeneration guard (#444/#486). Returns true when
+ * the accumulated text has grown at least DEGENERATION_CHECK_STEP bytes past the
+ * last-checked offset, so the pure rules only fire every ~2KB. Pure; the caller
+ * updates its watermark to `textLen` when this returns true.
+ *
+ * The watermark is an offset INTO the accumulator, so when the accumulator is
+ * reset to '' on a step boundary the caller MUST reset the watermark to 0 too
+ * (#486). Otherwise `textLen - lastCheckLen` goes negative after the reset and
+ * this returns false until a later step re-grows past the stale offset — a whole
+ * degenerate step could stream unchecked.
+ */
+export function shouldCheckDegeneration(
+  textLen: number,
+  lastCheckLen: number,
+): boolean {
+  return textLen - lastCheckLen >= DEGENERATION_CHECK_STEP;
+}
+
+/**
+ * Truncate a degenerated tail before persist so hundreds of KB of garbage never
+ * reach the DB / replay (#444). Keeps everything up to and including the FIRST
+ * `keepRepeats` repeats of the detected loop, then appends a short marker. If no
+ * loop is detected the text is returned unchanged (by identity).
+ *
+ * Implementation: find the shortest tail period (same check as hasPeriodicTail),
+ * keep the prefix before the loop plus `keepRepeats` copies of the block, drop
+ * the rest. This is best-effort cosmetic trimming; correctness does not depend on
+ * finding the exact minimal loop. Pure.
+ */
+export function truncateDegeneratedTail(
+  text: string,
+  keepRepeats = 3,
+): string {
+  const marker = '\n…[output truncated: repeated token loop detected]';
+  // Try the line rule first: collapse a long run of identical lines.
+  const lines = text.split('\n');
+  let runStart = -1;
+  let run = 1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].length > 0 && lines[i] === lines[i - 1]) {
+      if (run === 1) runStart = i - 1;
+      run += 1;
+      if (run >= REPEATED_LINES_THRESHOLD) {
+        const kept = lines.slice(0, runStart + keepRepeats).join('\n');
+        return kept + marker;
+      }
+    } else {
+      run = 1;
+      runStart = -1;
+    }
+  }
+
+  // Fall back to periodicity over the whole string (bounded by the same block
+  // length). Find the smallest period that makes the SUFFIX highly repetitive.
+  const n = text.length;
+  const maxP = Math.min(MAX_PERIOD_LEN, Math.floor(n / MIN_PERIOD_REPEATS));
+  for (let p = 1; p <= maxP; p++) {
+    // Count how many trailing p-blocks are periodic.
+    let reps = 1;
+    let i = n - 1;
+    for (; i >= p; i--) {
+      if (text[i] !== text[i - p]) break;
+    }
+    // The loop above walks over the periodic suffix; its length is (n-1 - i).
+    const periodicLen = n - 1 - i;
+    reps = Math.floor(periodicLen / p) + 1;
+    if (reps >= MIN_PERIOD_REPEATS) {
+      const loopStart = n - reps * p; // start of the fully-periodic suffix
+      const kept = text.slice(0, loopStart + keepRepeats * p);
+      return kept + marker;
+    }
+  }
+  return text;
+}

apps/server/src/core/ai-chat/public-share-chat.error-leak.spec.ts

@@ -0,0 +1,241 @@
+// Break the editor-ext import chain (share.service -> collaboration.util ->
+// @docmost/editor-ext -> @tiptap/core) that is unresolvable in this jest env and
+// pre-existingly breaks these specs. jsonToMarkdown is never reached in these
+// tests (the tools fail before rendering markdown).
+jest.mock('../../collaboration/collaboration.util', () => ({
+  jsonToMarkdown: () => '',
+}));
+
+import { Logger } from '@nestjs/common';
+import { MockLanguageModelV3, simulateReadableStream } from 'ai/test';
+import { PublicShareChatService } from './public-share-chat.service';
+import { PublicShareChatToolsService } from './tools/public-share-chat-tools.service';
+
+/**
+ * SECURITY integration guard for #394 (commit 5): a tool's or the provider's raw
+ * error text must NOT leak to an anonymous public-share reader.
+ *
+ * The render gate (ToolCallCard showErrors=false) hides the text in the DOM but
+ * NOT on the wire, so this test asserts on the RAW SSE BYTES the server writes —
+ * exactly the channel the render gate masks. We drive the real
+ * PublicShareChatService.stream() with a real share toolset (its underlying
+ * services mocked to fail) and a mock model, then inspect every byte piped to the
+ * fake socket.
+ */
+
+// A minimal ServerResponse stand-in that records every written chunk.
+class FakeSocket {
+  chunks: string[] = [];
+  statusCode = 200;
+  writableEnded = false;
+  destroyed = false;
+  headersSent = false;
+  writeHead(): this {
+    this.headersSent = true;
+    return this;
+  }
+  setHeader(): void {}
+  removeHeader(): void {}
+  getHeader(): undefined {
+    return undefined;
+  }
+  flushHeaders(): void {}
+  write(chunk: unknown): boolean {
+    this.chunks.push(
+      typeof chunk === 'string' ? chunk : Buffer.from(chunk as never).toString('utf8'),
+    );
+    return true;
+  }
+  end(chunk?: unknown): void {
+    if (chunk) this.write(chunk);
+    this.writableEnded = true;
+  }
+  on(): this {
+    return this;
+  }
+  once(): this {
+    return this;
+  }
+  get body(): string {
+    return this.chunks.join('');
+  }
+}
+
+/** Mock model that issues one getSharePage tool call, then finishes with text. */
+function toolCallingModel(): MockLanguageModelV3 {
+  let call = 0;
+  return new MockLanguageModelV3({
+    doStream: async () => {
+      call++;
+      if (call === 1) {
+        return {
+          stream: simulateReadableStream({
+            chunks: [
+              { type: 'stream-start' as const, warnings: [] },
+              { type: 'tool-input-start' as const, id: 't1', toolName: 'getSharePage' },
+              { type: 'tool-input-end' as const, id: 't1' },
+              {
+                type: 'tool-call' as const,
+                toolCallId: 't1',
+                toolName: 'getSharePage',
+                input: '{"pageId":"secret-page"}',
+              },
+              {
+                type: 'finish' as const,
+                finishReason: { unified: 'tool-calls' as const, raw: 'tool_calls' },
+                usage: {
+                  inputTokens: { total: 1, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
+                  outputTokens: { total: 1, text: 1, reasoning: undefined },
+                },
+              },
+            ],
+          }),
+        };
+      }
+      return {
+        stream: simulateReadableStream({
+          chunks: [
+            { type: 'stream-start' as const, warnings: [] },
+            { type: 'text-start' as const, id: '1' },
+            { type: 'text-delta' as const, id: '1', delta: 'Sorry.' },
+            { type: 'text-end' as const, id: '1' },
+            {
+              type: 'finish' as const,
+              finishReason: { unified: 'stop' as const, raw: 'stop' },
+              usage: {
+                inputTokens: { total: 1, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
+                outputTokens: { total: 1, text: 1, reasoning: undefined },
+              },
+            },
+          ],
+        }),
+      };
+    },
+  });
+}
+
+/** Mock model whose stream emits a provider error carrying an internal secret. */
+function providerErrorModel(secret: string): MockLanguageModelV3 {
+  return new MockLanguageModelV3({
+    doStream: async () => ({
+      stream: simulateReadableStream({
+        chunks: [
+          { type: 'stream-start' as const, warnings: [] },
+          {
+            type: 'error' as const,
+            error: {
+              statusCode: 503,
+              message: 'Service Unavailable',
+              responseBody: `upstream ${secret} model=internal-gpt`,
+            },
+          },
+        ],
+      }),
+    }),
+  });
+}
+
+function makeService(toolsService: PublicShareChatToolsService): {
+  svc: PublicShareChatService;
+  logSpy: jest.SpyInstance;
+} {
+  const svc = Object.create(PublicShareChatService.prototype);
+  const logger = new Logger('test');
+  const logSpy = jest.spyOn(logger, 'error').mockImplementation(() => undefined);
+  jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+  svc.tools = toolsService;
+  svc.logger = logger;
+  svc.tokenBudget = { record: jest.fn().mockResolvedValue(undefined) };
+  return { svc, logSpy };
+}
+
+async function runStream(
+  svc: PublicShareChatService,
+  model: MockLanguageModelV3,
+): Promise<FakeSocket> {
+  const socket = new FakeSocket();
+  await svc.stream({
+    workspaceId: 'ws1',
+    shareId: 'share1',
+    share: { id: 'share1', pageId: 'p1', sharedPage: { id: 'p1', title: 'Docs' } },
+    openedPage: null,
+    messages: [
+      { id: 'm1', role: 'user', parts: [{ type: 'text', text: 'read the page' }] } as never,
+    ],
+    res: { raw: socket } as never,
+    signal: new AbortController().signal,
+    model: model as never,
+    role: null,
+  });
+  // Let the piped stream drain fully.
+  await new Promise((r) => setTimeout(r, 300));
+  return socket;
+}
+
+describe('public share chat error leak (#394)', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('does NOT leak a tool\'s raw internal error to the SSE bytes (generic classified string instead)', async () => {
+    const SECRET = 'INTERNAL_baseUrl_http://provider.internal:8080/v1';
+    const shareService = {
+      // The canonical boundary throws a RAW internal error (with a secret).
+      resolveReadableSharePage: jest
+        .fn()
+        .mockRejectedValue(new Error(`db failed at ${SECRET} stack@line42`)),
+    };
+    const tools = new PublicShareChatToolsService(
+      shareService as never,
+      {} as never,
+      {} as never,
+    );
+    const { svc } = makeService(tools);
+
+    const socket = await runStream(svc, toolCallingModel());
+
+    // The tool-output-error frame is present on the wire...
+    expect(socket.body).toContain('tool-output-error');
+    // ...but it carries ONLY the generic classified string — never the secret,
+    // the raw driver message, or a stack fragment.
+    expect(socket.body).toContain('The tool could not complete the request.');
+    expect(socket.body).not.toContain(SECRET);
+    expect(socket.body).not.toContain('stack@line42');
+    expect(socket.body).not.toContain('db failed');
+  });
+
+  it('passes a SAFE ShareToolError message (page not available) through to the bytes', async () => {
+    const shareService = {
+      // Not found in this share -> the tool throws the classified SAFE message.
+      resolveReadableSharePage: jest.fn().mockResolvedValue(null),
+    };
+    const tools = new PublicShareChatToolsService(
+      shareService as never,
+      {} as never,
+      {} as never,
+    );
+    const { svc } = makeService(tools);
+
+    const socket = await runStream(svc, toolCallingModel());
+    expect(socket.body).toContain('tool-output-error');
+    expect(socket.body).toContain('not available in this share');
+  });
+
+  it('does NOT leak a provider error (statusCode + response body) to the SSE bytes', async () => {
+    const SECRET = 'http://provider.internal:8080';
+    const tools = new PublicShareChatToolsService(
+      {} as never,
+      {} as never,
+      {} as never,
+    );
+    const { svc, logSpy } = makeService(tools);
+
+    const socket = await runStream(svc, providerErrorModel(SECRET));
+
+    // The anon sees a fixed classified string, not the provider body/baseUrl/model.
+    expect(socket.body).toContain('temporarily unavailable');
+    expect(socket.body).not.toContain(SECRET);
+    expect(socket.body).not.toContain('internal-gpt');
+    // The FULL provider detail is logged server-side only.
+    const logged = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+    expect(logged).toContain(SECRET);
+  });
+});

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

@@ -12,7 +12,10 @@ import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles
 import { AiAgentRole } from '@docmost/db/types/entity.types';
 import { AiService } from '../../integrations/ai/ai.service';
 import { AiSettingsService } from '../../integrations/ai/ai-settings.service';
-import { PublicShareChatToolsService } from './tools/public-share-chat-tools.service';
+import {
+  PublicShareChatToolsService,
+  ShareToolError,
+} from './tools/public-share-chat-tools.service';
 import { buildShareSystemPrompt } from './public-share-chat.prompt';
 import { roleModelOverride } from './roles/role-model-config';
 import {
@@ -102,6 +105,30 @@ export function filterShareTranscript(messages: UIMessage[]): UIMessage[] {
   );
 }
 
+/**
+ * Fixed, classified strings an ANONYMOUS share reader may see when the assistant
+ * stream fails (#394). These reveal NOTHING about the internal provider, its
+ * baseUrl, the model name, or the raw response body — unlike describeProviderError
+ * (which is for the server log / the authenticated operator only). We classify by
+ * HTTP status where available so the reader still gets a useful hint (retry vs.
+ * give up) without any internal detail.
+ */
+export function classifyAnonStreamError(error: unknown): string {
+  const status =
+    typeof error === 'object' && error !== null
+      ? (error as { statusCode?: number }).statusCode
+      : undefined;
+  if (status === 429) {
+    return 'The assistant is receiving too many requests right now. Please try again shortly.';
+  }
+  if (typeof status === 'number' && status >= 500) {
+    return 'The assistant is temporarily unavailable. Please try again.';
+  }
+  // Any other failure (including a bare connection error with no status): a
+  // single neutral line. No provider identity, no config, no response body.
+  return 'The assistant could not complete your request. Please try again.';
+}
+
 /**
  * Anonymous, read-only AI assistant for a single PUBLIC share tree.
  *
@@ -318,11 +345,28 @@ export class PublicShareChatService {
       result.pipeUIMessageStreamToResponse(res.raw, {
         headers: { 'X-Accel-Buffering': 'no' },
         onError: (error: unknown) => {
-          // Reuse the shared formatter so provider error formatting stays
-          // unified between the log line and the streamed error message — a
-          // share reader sees 402/429/503 causes consistently with the
-          // authenticated path.
-          return describeProviderError(error, 'AI stream error');
+          // SECURITY (#394): the string this returns is written verbatim into the
+          // SSE error frame delivered to an ANONYMOUS reader (for a tool failure
+          // it becomes the atomic `tool-output-error` frame's errorText; for a
+          // stream/provider failure, the terminal error frame).
+          //
+          // A ShareToolError is already a classified, safe tool message (see
+          // PublicShareChatToolsService.wrapToolErrors) — pass it through so the
+          // reader still gets the useful "page not available in this share" hint.
+          if (error instanceof ShareToolError) {
+            return error.message;
+          }
+          // Anything else is a provider/stream error. describeProviderError
+          // bundles the provider statusCode AND response body, which can carry the
+          // internal baseUrl or model name — NEVER expose that to the public. Log
+          // the full detail server-side only and return a fixed classified string.
+          this.logger.error(
+            `Public share chat pipe error: ${describeProviderError(
+              error,
+              'AI stream error',
+            )}`,
+          );
+          return classifyAnonStreamError(error);
         },
       });
 

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

@@ -1,6 +1,17 @@
 import { AiChatToolsService } from './ai-chat-tools.service';
 import * as loader from './docmost-client.loader';
 import type { DocmostClientLike } from './docmost-client.loader';
+
+// Test-double type for the loopback client. `DocmostClientLike` is now DERIVED
+// from the real `DocmostClient` (issue #446), so its method RETURN types are the
+// concrete client shapes. These stubs deliberately return minimal recording
+// shapes (e.g. `{ ok: true }`), which no longer satisfy those concrete returns —
+// so the doubles are typed with the same method NAMES but loose async returns.
+// Each is still cast to `DocmostClientLike` at the (return-erased) mock site, so
+// the positional-call type-safety on the PRODUCTION client is unaffected.
+type FakeDocmostClient = Partial<
+  Record<keyof DocmostClientLike, (...args: any[]) => Promise<any>>
+>;
 // The real zod-agnostic shared tool-spec registry. It has no runtime deps, so
 // importing the TS source directly keeps these mocks honest: the service builds
 // the shared tools from exactly the specs the package ships, not a hand-stub.
@@ -12,7 +23,15 @@ import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs
 // sync.
 const mockLoaded = (DocmostClient: loader.DocmostClientCtor) => ({
   DocmostClient,
-  sharedToolSpecs: SHARED_TOOL_SPECS as Record<string, loader.SharedToolSpec>,
+  sharedToolSpecs: SHARED_TOOL_SPECS as unknown as Record<string, loader.SharedToolSpec>,
+  // Pure no-network draw.io helpers (#424). Type-correct stubs: these tests
+  // never execute the drawioShapes / drawioGuide tool bodies.
+  searchShapes: (() => []) as unknown as loader.SearchShapesFn,
+  getGuideSection: (() => ({
+    section: 'index',
+    content: '',
+    sections: [],
+  })) as unknown as loader.GetGuideSectionFn,
 });
 
 /**
@@ -31,7 +50,7 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
 
   // Minimal fake DocmostClient: only the write methods the tools touch need to
   // exist; deletePage records its args. No network, no ESM import.
-  const fakeClient: Partial<DocmostClientLike> = {
+  const fakeClient: FakeDocmostClient = {
     deletePage: (...args: unknown[]) => {
       deletePageCalls.push(args);
       return Promise.resolve({ success: true });
@@ -160,7 +179,7 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
 describe('AiChatToolsService expanded toolset guardrails', () => {
   // No client method is invoked here — every assertion is on tool presence /
   // input schema — so an empty fake client is sufficient.
-  const fakeClient: Partial<DocmostClientLike> = {};
+  const fakeClient: FakeDocmostClient = {};
 
   const tokenServiceStub = {
     generateAccessToken: jest.fn().mockResolvedValue('access-token'),
@@ -264,8 +283,9 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
   const patchNodeCalls: unknown[][] = [];
   const insertNodeCalls: unknown[][] = [];
   const updatePageJsonCalls: unknown[][] = [];
+  const updatePageCalls: unknown[][] = [];
 
-  const fakeClient: Partial<DocmostClientLike> = {
+  const fakeClient: FakeDocmostClient = {
     patchNode: (...args: unknown[]) => {
       patchNodeCalls.push(args);
       return Promise.resolve({ ok: true });
@@ -278,6 +298,11 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
       updatePageJsonCalls.push(args);
       return Promise.resolve({ ok: true });
     },
+    // Backs the plain-Markdown full-body-replace tool updatePageMarkdown (#411).
+    updatePage: (...args: unknown[]) => {
+      updatePageCalls.push(args);
+      return Promise.resolve({ success: true });
+    },
   };
 
   const tokenServiceStub = {
@@ -291,6 +316,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
     patchNodeCalls.length = 0;
     insertNodeCalls.length = 0;
     updatePageJsonCalls.length = 0;
+    updatePageCalls.length = 0;
     jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue(
       mockLoaded(function () {
         return fakeClient as DocmostClientLike;
@@ -329,23 +355,32 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
     content: [{ type: 'text', text: 'Hello' }],
   };
 
-  it('patchNode parses a JSON-string node and forwards it as an object', async () => {
+  it('patchNode parses a JSON-string node and forwards it as { node } (object)', async () => {
     const tools = await buildTools();
     await tools.patchNode.execute(
       { pageId: 'p1', nodeId: 'n1', node: JSON.stringify(NODE_OBJ) } as never,
       {} as never,
     );
     expect(patchNodeCalls).toHaveLength(1);
-    expect(patchNodeCalls[0]).toEqual(['p1', 'n1', NODE_OBJ]);
+    // #413: the 3rd arg is now the XOR input { markdown?, node? }.
+    expect(patchNodeCalls[0]).toEqual([
+      'p1',
+      'n1',
+      { markdown: undefined, node: NODE_OBJ },
+    ]);
   });
 
-  it('patchNode passes an object node through unchanged', async () => {
+  it('patchNode passes an object node through unchanged inside { node }', async () => {
     const tools = await buildTools();
     await tools.patchNode.execute(
       { pageId: 'p1', nodeId: 'n1', node: NODE_OBJ } as never,
       {} as never,
     );
-    expect(patchNodeCalls[0]).toEqual(['p1', 'n1', NODE_OBJ]);
+    expect(patchNodeCalls[0]).toEqual([
+      'p1',
+      'n1',
+      { markdown: undefined, node: NODE_OBJ },
+    ]);
   });
 
   it('patchNode throws the documented message on invalid JSON string', async () => {
@@ -359,7 +394,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
     expect(patchNodeCalls).toHaveLength(0);
   });
 
-  it('insertNode parses a JSON-string node and forwards it as an object', async () => {
+  it('insertNode parses a JSON-string node and forwards it inside { node }', async () => {
     const tools = await buildTools();
     await tools.insertNode.execute(
       {
@@ -370,9 +405,15 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
       {} as never,
     );
     expect(insertNodeCalls).toHaveLength(1);
-    const [pageId, node] = insertNodeCalls[0];
+    // #413: the 2nd arg is the XOR input { markdown?, node? }, the 3rd is opts.
+    const [pageId, input, opts] = insertNodeCalls[0] as [
+      string,
+      { markdown?: unknown; node?: unknown },
+      { position?: string },
+    ];
     expect(pageId).toBe('p1');
-    expect(node).toEqual(NODE_OBJ);
+    expect(input).toEqual({ markdown: undefined, node: NODE_OBJ });
+    expect(opts.position).toBe('append');
   });
 
   it('insertNode throws the documented message on invalid JSON string', async () => {
@@ -426,6 +467,54 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
     ).rejects.toThrow('content was a string but not valid JSON');
     expect(updatePageJsonCalls).toHaveLength(0);
   });
+
+  // #411: the plain-Markdown full-body-replace tool is now the shared
+  // `updatePageMarkdown` (was inline `updatePageContent`). It forwards to
+  // client.updatePage(pageId, content, title) -> updatePageContentRealtime ->
+  // markdownToProseMirrorCanonical, so `^[...]` footnotes materialize.
+  it('updatePageMarkdown forwards { pageId, content, title } to client.updatePage', async () => {
+    const tools = await buildTools();
+    await tools.updatePageMarkdown.execute(
+      { pageId: 'p1', content: 'Body^[a note]', title: 'New title' } as never,
+      {} as never,
+    );
+    expect(updatePageCalls).toHaveLength(1);
+    expect(updatePageCalls[0]).toEqual(['p1', 'Body^[a note]', 'New title']);
+  });
+
+  it('updatePageMarkdown returns the RAW client result in-app (deliberate #411 shape change, documented on the spec)', async () => {
+    const tools = await buildTools();
+    // Registry canonical execute returns client.updatePage's result verbatim.
+    // The old inline tool projected to { pageId, updated }; the rename now
+    // surfaces the raw result (nothing reads the removed `.updated`; the raw
+    // shape carries footnote/verify warnings and matches the on-both-hosts
+    // registry convention). fakeClient.updatePage resolves { success: true }.
+    const result = await tools.updatePageMarkdown.execute(
+      { pageId: 'p1', content: '# Hi' } as never,
+      {} as never,
+    );
+    expect(result).toEqual({ success: true });
+  });
+
+  it('updatePageMarkdown forwards title=undefined when omitted', async () => {
+    const tools = await buildTools();
+    await tools.updatePageMarkdown.execute(
+      { pageId: 'p1', content: '# Hi' } as never,
+      {} as never,
+    );
+    expect(updatePageCalls[0]).toEqual(['p1', '# Hi', undefined]);
+  });
+
+  // #411 surface split: the plain-Markdown replace tool exists in-app under the
+  // new key; the OLD inline updatePageContent key is gone; importPageMarkdown is
+  // still present IN-APP (only the external MCP surface drops it — asserted in
+  // packages/mcp/test/unit/tool-inventory.test.mjs).
+  it('exposes updatePageMarkdown in-app, no legacy updatePageContent, keeps importPageMarkdown', async () => {
+    const tools = await buildTools();
+    expect(tools.updatePageMarkdown).toBeDefined();
+    expect((tools as Record<string, unknown>).updatePageContent).toBeUndefined();
+    expect(tools.importPageMarkdown).toBeDefined();
+  });
 });
 
 /**
@@ -439,7 +528,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
  * getOutline) are exercised here end-to-end through forUser().
  */
 describe('AiChatToolsService model-friendly input validation (#190)', () => {
-  const fakeClient: Partial<DocmostClientLike> = {};
+  const fakeClient: FakeDocmostClient = {};
   const tokenServiceStub = {
     generateAccessToken: jest.fn().mockResolvedValue('access-token'),
     generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
@@ -557,7 +646,7 @@ describe('AiChatToolsService #294 changed execute wirings', () => {
     tableDeleteRow: [],
     tableUpdateCell: [],
   };
-  const fakeClient: Partial<DocmostClientLike> = {
+  const fakeClient: FakeDocmostClient = {
     movePage: (...args: unknown[]) => {
       calls.movePage.push(args);
       return Promise.resolve({ success: true });
@@ -666,7 +755,7 @@ describe('AiChatToolsService #410 footnote + image tools', () => {
     insertImage: [],
     replaceImage: [],
   };
-  const fakeClient: Partial<DocmostClientLike> = {
+  const fakeClient: FakeDocmostClient = {
     insertFootnote: (...args: unknown[]) => {
       calls.insertFootnote.push(args);
       return Promise.resolve({ success: true, footnoteId: 'fn1', reused: false });
@@ -836,3 +925,109 @@ describe('AiChatToolsService getCurrentPage selection (#388)', () => {
     );
   });
 });
+
+/**
+ * #440 review: the in-app drawioCreate / drawioUpdate handlers must forward
+ * the optional `layout:"elk"` param to the client (5th positional arg), exactly
+ * like the MCP host. It was silently dropped, so ELK auto-layout worked only via
+ * the standalone MCP server, not in-app. These tests pin per-host parity.
+ */
+describe('AiChatToolsService drawio layout passthrough (#440)', () => {
+  const createCalls: unknown[][] = [];
+  const updateCalls: unknown[][] = [];
+
+  // FakeDocmostClient (not Partial<DocmostClientLike>): since #446 derived
+  // DocmostClientLike from the real client, its drawioCreate/drawioUpdate return
+  // the concrete result shape, so a minimal stub object would not be assignable.
+  // FakeDocmostClient types every method as (...args) => Promise<any>, which is
+  // exactly what these arg-capturing doubles need.
+  const fakeClient: FakeDocmostClient = {
+    drawioCreate: (...args: unknown[]) => {
+      createCalls.push(args);
+      return Promise.resolve({ success: true, nodeId: '#0' });
+    },
+    drawioUpdate: (...args: unknown[]) => {
+      updateCalls.push(args);
+      return Promise.resolve({ success: true, nodeId: '#0' });
+    },
+  };
+
+  const tokenServiceStub = {
+    generateAccessToken: jest.fn().mockResolvedValue('access-token'),
+    generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
+  };
+
+  let service: AiChatToolsService;
+
+  beforeEach(() => {
+    createCalls.length = 0;
+    updateCalls.length = 0;
+    jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue(
+      mockLoaded(function () {
+        return fakeClient as DocmostClientLike;
+      } as unknown as loader.DocmostClientCtor),
+    );
+    service = new AiChatToolsService(
+      tokenServiceStub as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      {
+        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
+      } as never,
+    );
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  const buildTools = () =>
+    service.forUser(
+      { id: 'user-1', email: 'u@example.com', workspaceId: 'ws-1' } as never,
+      'session-1',
+      'ws-1',
+      'chat-1',
+    );
+
+  it('forwards layout:"elk" to client.drawioCreate as the 5th positional arg', async () => {
+    const tools = await buildTools();
+    await tools.drawioCreate.execute(
+      {
+        pageId: 'p-1',
+        xml: '<mxGraphModel/>',
+        position: 'append',
+        layout: 'elk',
+      } as never,
+      {} as never,
+    );
+    expect(createCalls).toHaveLength(1);
+    // drawioCreate(pageId, where, xml, title, layout) — layout is args[4].
+    expect(createCalls[0][4]).toBe('elk');
+  });
+
+  it('forwards layout:"elk" to client.drawioUpdate as the 5th positional arg', async () => {
+    const tools = await buildTools();
+    await tools.drawioUpdate.execute(
+      {
+        pageId: 'p-1',
+        node: '#0',
+        xml: '<mxGraphModel/>',
+        baseHash: 'h',
+        layout: 'elk',
+      } as never,
+      {} as never,
+    );
+    expect(updateCalls).toHaveLength(1);
+    // drawioUpdate(pageId, node, xml, baseHash, layout) — layout is args[4].
+    expect(updateCalls[0][4]).toBe('elk');
+  });
+
+  it('omits layout (undefined 5th arg) when not requested', async () => {
+    const tools = await buildTools();
+    await tools.drawioCreate.execute(
+      { pageId: 'p-1', xml: '<mxGraphModel/>', position: 'append' } as never,
+      {} as never,
+    );
+    expect(createCalls[0][4]).toBeUndefined();
+  });
+});