refactor(mcp): убрать мёртвый runtime-слой page-id, оставить бренд PageId

Ревью #516: isPageId/asPageId/isSlugId/asSlugId/SLUG_ID_RE + типы SlugId/PageRef
имели НОЛЬ вызовов в монорепе — только барные ре-экспорты в client.ts и кейсы
теста. Несущий смысл — только compile-time бренд PageId (минтится as PageId в
resolvePageId, единственном узле канонизации; asPageId туда намеренно не звался).
Докстринг заявлял «asPageId() guards the untrusted PUBLIC boundary» — но никто не
звал: спекулятивный вес.

Удалил мёртвые runtime-символы + типы SlugId/PageRef + ре-экспорты + их тест-файл.
Оставил тип PageId + касты. Поправил врущий коммент в resolvePageId (бренд —
чистый compile-time маркер, гарантия — что этот узел единственный производитель).

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

.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
@@ -191,11 +225,26 @@ MCP_DOCMOST_PASSWORD=
 
 # Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
 # Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in
-# ~1 min instead of 15. Note it also cuts a legitimately long but byte-silent
-# single tool call (a slow crawl that emits nothing until done) and an SSE
-# transport idling >1 min BETWEEN tool calls. Default 60000 (1 min).
+# ~1 min instead of 15. It cuts a legitimately long but byte-silent single tool
+# call (a slow crawl that emits nothing until done) on the HTTP (streamable)
+# transport, which opens a fresh request per call. The SSE transport — one
+# long-lived body across many calls — is NO LONGER governed by this timeout
+# (as of #489): its idle-BETWEEN-calls window has its own, raised bodyTimeout,
+# AI_MCP_SSE_BODY_TIMEOUT_MS below. Default 60000 (1 min).
 # AI_MCP_STREAM_TIMEOUT_MS=60000
 
+# bodyTimeout (ms) for the EXTERNAL-MCP SSE transport ONLY (#489). The SSE
+# transport holds ONE response body open across many tool calls, so undici's
+# bodyTimeout (time between body bytes) counts the LEGITIMATE silence BETWEEN the
+# model's tool calls, not just a hung single call. At the tight 1-min silence
+# timeout above, a normal >1-min gap between calls would break the SSE socket and
+# the cache would serve a dead client until TTL — so the SSE transport gets its
+# OWN, RAISED bodyTimeout. A single stuck call is still bounded by the per-call
+# cap (AI_MCP_CALL_TIMEOUT_MS), and a socket that does break is healed by the
+# in-run transport-error retry. The HTTP (streamable) transport keeps the tight
+# timeout. Default 600000 (10 min).
+# AI_MCP_SSE_BODY_TIMEOUT_MS=600000
+
 # Total wall-clock cap (ms) for ONE external MCP tool call (app-level, not
 # transport). Aborts a tool that keeps the socket warm (SSE heartbeats / trickle)
 # but never returns a result — which the silence timeout above never breaks.
@@ -217,6 +266,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
@@ -243,6 +303,29 @@ MCP_DOCMOST_PASSWORD=
 # registry is process-local).
 # AI_CHAT_RESUMABLE_STREAM=false
 
+# --- Run lifecycle tunables (#487) ---
+# These govern the universal run machinery (every turn is now a first-class run,
+# both modes) and rarely need changing.
+#
+# How long a server-side SUPERSEDE ("interrupt and send now") waits for the target
+# run to settle after issuing Stop before it degrades to a 409 SUPERSEDE_TIMEOUT
+# (nothing sent, the composer keeps the user's text). 10s is generous under a
+# healthy DB; do NOT raise it to paper over a slow DB — a SUPERSEDE_TIMEOUT is the
+# honest signal. Default 10000 (10s).
+# AI_CHAT_SUPERSEDE_TIMEOUT_MS=10000
+#
+# How often the periodic bidirectional reconcile job runs (heals runs/messages
+# left dangling by a crash or a lost terminal write). Default 120000 (2 min).
+# AI_CHAT_RECONCILE_INTERVAL_MS=120000
+#
+# Wall-clock cap for a SINGLE in-app tool call (a long paginated read, or a content
+# write whose collab commit hangs) — the per-call half of the composite abort
+# signal every in-app tool is wrapped with (the other half is the turn's Stop).
+# The reconcile staleness floor is derived as max(2 x this cap, 15min), so a very
+# high value delays stale-run recovery (the server boot-warns above 30min). Default
+# 120000 (2 min).
+# AI_CHAT_INAPP_TOOL_CALL_CAP_MS=120000
+
 # --- Anonymous public-share AI assistant ---
 # Opt-in per workspace (AI settings -> "public share assistant"; off by default).
 # When enabled, anonymous visitors of a published share can ask an AI about that
@@ -290,6 +373,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/nightly-property.yml

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

.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

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
@@ -201,7 +334,7 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 | `apps/client` | `client` | React 18 + Vite + Mantine 8 + TanStack Query + Jotai | SPA frontend |
 | `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
 | `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Consumes the shared converter/schema from `@docmost/prosemirror-markdown` (#293) — it no longer carries its own vendored converter/schema copy |
-| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp`, `git-sync`, AND `apps/server` (server-side markdown import/export, #345); there is exactly ONE copy of the converter now |
+| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked; jsdom (Node only) | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp`, `git-sync`, `apps/server` (server-side markdown import/export, #345), AND `apps/client` (markdown paste/copy + AI-chat render, via the `browser` entry — native `DOMParser`, no jsdom in the client bundle, #347); there is exactly ONE copy of the converter now |
 
 `build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
 
@@ -322,12 +455,12 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
    - `core/ai-chat/tools/` — the agent's ~40 read+write tools. Every tool runs under the **calling user's** CASL permissions via a per-user loopback access token (`docmost-client.loader.ts`), so the agent can never exceed what the user could do. Only **reversible** operations are exposed (page history + trash; no permanent delete). Agent edits get an "AI agent" provenance badge in page history (`20260616T130000-agent-provenance` migration).
    - `core/ai-chat/embedding/` — RAG indexer + a BullMQ consumer on `AI_QUEUE` that embeds pages into `page_embeddings` (vector search), complementing Postgres full-text search. Pages are (re)indexed on edit; `AI_EMBEDDING_TIMEOUT_MS` bounds a hung embeddings endpoint.
    - `core/ai-chat/external-mcp/` — admins can attach external MCP servers (e.g. Tavily) to give the agent web access. **`ssrf-guard.ts` validates outbound MCP URLs against SSRF** — keep that guard in the path when touching external-MCP connection logic.
-   - `core/ai-chat/ai-chat-run.service.ts` + `ai_chat_runs` — **detached/autonomous agent runs** (`#184`), behind the per-workspace `settings.ai.autonomousRuns` flag (off by default). When on, a turn becomes a server-side RUN that survives a browser disconnect; only an explicit `POST /ai-chat/stop` ends it, and a client reconnects/live-follows via `POST /ai-chat/run`. **DEPLOY CONSTRAINT — single-instance only in phase 1:** Stop and the AbortController that backs it are process-local, so a Stop only aborts a run executing on the **same** replica that owns it (cross-instance pub/sub stop is phase 2). Do **not** enable `autonomousRuns` on a horizontally-scaled deployment (multiple replicas behind a load balancer, or Docmost cloud `CLOUD=true`) — run a single instance instead. The server logs a startup WARNING when it detects a multi-instance deployment (`CLOUD=true`) so the constraint is visible. The startup sweep settles any run left dangling by a restart.
+   - `core/ai-chat/ai-chat-run.service.ts` + `ai_chat_runs` — **every agent turn is now a first-class server-side RUN** (`#184`, universalized in `#487`): its lifecycle is tracked in `ai_chat_runs` in **both** modes, and the single-active-run-per-chat concurrency gate is enforced universally (a legacy second tab now gets a clean `409 A_RUN_ALREADY_ACTIVE` instead of a second parallel stream that interleaved history). The per-workspace `settings.ai.autonomousRuns` flag (off by default) **no longer gates whether a turn is a run** — it now controls **only the browser-disconnect semantics**: when ON the run is *detached* (a disconnect leaves it executing server-side; only an explicit `POST /ai-chat/stop` ends it, and a client reconnects/live-follows via `POST /ai-chat/run`); when OFF (legacy) a disconnect ends the turn by stopping its run via the run's stop lever. `#487` also adds a server-side **supersede** CAS ("interrupt and send now") to `POST /ai-chat/stream` (`supersede: { runId }`): it atomically stops the chat's currently-active run and waits for it to settle before the new turn claims the slot, returning `SUPERSEDE_INVALID` / `SUPERSEDE_TARGET_MISMATCH` / `SUPERSEDE_TIMEOUT` on the non-proceed branches. **DEPLOY CONSTRAINT — single-instance only in phase 1:** Stop and the AbortController that backs it are process-local, so a Stop only aborts a run executing on the **same** replica that owns it (cross-instance pub/sub stop is phase 2). Do **not** enable `autonomousRuns` on a horizontally-scaled deployment (multiple replicas behind a load balancer, or Docmost cloud `CLOUD=true`) — run a single instance instead. The server logs a startup WARNING when it detects a multi-instance deployment (`CLOUD=true`) so the constraint is visible. The startup sweep settles any run left dangling by a restart.
 
 ### Client structure
 Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:
 - **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
-- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, and `apps/server` (#345) — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence. For the converter's property-testing and counterexample→fixture process (P1–P4 invariants, the `PROPERTY_SEED`/`PROPERTY_NUM_RUNS` knobs, and the nightly fuzz workflow), see `packages/prosemirror-markdown/README.md`.
+- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, `apps/server` (#345), and `apps/client` (#347) — do NOT reintroduce a per-package copy. The client uses the package's `browser` entry (`@docmost/prosemirror-markdown/browser`): markdown paste (`markdown-clipboard.ts`), copy-as-markdown, and AI-chat rendering now all go through the canonical converter, so the hand-written `marked`/`turndown` markdown layer that used to live in `editor-ext` was deleted (#347). The browser entry runs the HTML→DOM stage on the native `DOMParser`, so jsdom stays out of the client bundle. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence. For the converter's property-testing and counterexample→fixture process (P1–P4 invariants, the `PROPERTY_SEED`/`PROPERTY_NUM_RUNS` knobs, and the nightly fuzz workflow), see `packages/prosemirror-markdown/README.md`.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
 
@@ -337,8 +470,10 @@ 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`.
+  - **Upstream tracking (report the analysis upstream, don't just carry it):** both `ai` fixes and the hocuspocus one are candidates for upstreaming so we can eventually drop the local patch — the analysis is already written up in each patch's `PATCH(...)` header comments. File (a) an upstream **issue** on `vercel/ai` for the O(n²) cumulative `partialOutput` accumulation (heap OOM), (b) an upstream **issue** on `vercel/ai` for the `writeToServerResponse` drain-hang, and (c) an upstream **PR** on `@hocuspocus/server` for the connect-vs-unload race (local marker `PATCH(gitmost #401)` in `patches/@hocuspocus__server@3.4.4.patch`). Do NOT edit the patch files to add links — the patch bytes feed `patch_hash` in `pnpm-lock.yaml` (`ai@6.0.134` → `e8c599b3…`), so any content change there desyncs the lockfile pin and breaks `pnpm install`; keep upstream references here instead.
+  - **`ai` version is split across the monorepo and MUST be aligned deliberately, NOT casually:** the server pins `ai@6.0.134` (patched, exact — the `patchedDependencies` key forces that version), while the client declares `ai@6.0.207` (unpatched — the server-side `writeToServerResponse`/`partialOutput` fixes are dead code in the browser, so the mismatch is currently benign but is real drift). Alignment is a **planned, install-gated step**, never a bare `package.json` edit: (1) choose the target version; (2) re-create ALL THREE patch hunks (partialOutput publish-each, the `DefaultStreamTextResult` lazy-`output` wiring, and the drain-hang race) against the target dist via `pnpm patch` — the line offsets shift between versions, so the current patch WILL fail to apply as-is; (3) run a full `pnpm install` so the lockfile + new `patch_hash` regenerate together; (4) confirm both tripwire specs still find their markers. `pnpm install` FAILS HARD on an unapplied patch — that failure is the guardrail, so treat the port as a deliberate plan rather than discovering it as a deploy-time surprise.
+- **The MCP tool inventory in `SERVER_INSTRUCTIONS` is GENERATED from the registry** (`packages/mcp/src/server-instructions.ts`: `buildToolInventory()` over `SHARED_TOOL_SPECS`) and spliced into the hand-written routing prose (`ROUTING_PROSE`). So adding/renaming/removing a **shared** spec in `packages/mcp/src/tool-specs.ts` auto-updates the `<tool_inventory>` — no manual `SERVER_INSTRUCTIONS` edit needed. Only an **inline** MCP-only tool (those registered via `server.registerTool(...)` in `index.ts`, not through the registry) needs a one-line entry in `INLINE_MCP_INVENTORY`. Enforced by `packages/mcp/test/unit/tool-inventory.test.mjs`, which fails when a registered tool is missing from the generated inventory (there is no `EXCEPTIONS` opt-out anymore — every tool must appear). Update `ROUTING_PROSE` when a tool's *intent guidance* (when-to-use) changes. `packages/mcp/build/` is gitignored and rebuilt in CI/Docker via `pnpm build` (same convention as `git-sync`/`prosemirror-markdown`) — never commit it; rebuild locally after editing to run the tests.
 
 ## CI / release
 

CHANGELOG.md

@@ -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
@@ -85,6 +202,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   dangling by a restart. Phase 1 is single-instance-only (cross-instance Stop is
   not yet reliable); the server warns at startup on a horizontally-scaled
   deployment. (#184)
+- **Server-side "interrupt and send now" (supersede) for AI chat.** `POST
+  /ai-chat/stream` now accepts a `supersede: { runId }` field: when the user sends
+  a new message while a run is active, the server atomically stops that run and
+  waits for it to settle before the new turn claims the chat's single run slot,
+  instead of the send being rejected as concurrent. The compare-and-set surfaces
+  three codes on its non-proceed branches — `SUPERSEDE_INVALID` (the targeted run
+  is malformed / belongs to another chat), `SUPERSEDE_TARGET_MISMATCH` (a
+  different run is now active; carries the current `activeRunId`), and
+  `SUPERSEDE_TIMEOUT` (the previous run did not stop within the settle window, so
+  nothing was sent and the composer keeps the text). Tunable via
+  `AI_CHAT_SUPERSEDE_TIMEOUT_MS` (default 10s). (#487)
 - **Out-of-band page transfer via an in-RAM blob sandbox (`stash_page`).** A
   new MCP tool serializes a whole page (its full ProseMirror JSON, with every
   internal image/file mirrored) into an ephemeral in-RAM blob and returns only
@@ -146,9 +274,56 @@ 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
 
+- **Every AI-chat turn is now a first-class server-side run, and one run per chat
+  is enforced in both modes.** The run machinery from `#184` was universalized: a
+  turn is tracked in `ai_chat_runs` and gated by the single-active-run-per-chat
+  index regardless of the `settings.ai.autonomousRuns` flag. **Behavior change:**
+  a second tab (or a double-submit) that starts a turn while one is already active
+  on the chat is now rejected up front with `409 A_RUN_ALREADY_ACTIVE` (carrying
+  the `activeRunId`); previously, on the legacy path, it opened a second parallel
+  stream on the same chat that interleaved history. The `autonomousRuns` flag no
+  longer controls whether a turn is a run — it now governs **only** the
+  browser-disconnect semantics (ON = detached/survives a disconnect; OFF = a
+  disconnect stops the run). (#487)
+- **Vendor `ai` patch: upstream-tracking + version-alignment plan documented.**
+  The two local `ai@6.0.134` fixes (O(n²) `partialOutput` heap-OOM; the
+  `writeToServerResponse` drain-hang) and the hocuspocus connect-vs-unload race
+  now have explicit upstream-reporting and `ai`-version-alignment steps recorded
+  in `AGENTS.md` (client `ai@6.0.207` vs server `ai@6.0.134`-patched drift). The
+  patch bytes are unchanged — they feed the lockfile `patch_hash`, so the
+  alignment is called out as an install-gated plan rather than a bare version
+  bump. No runtime change.
+- **Client markdown paste/copy and AI-chat rendering now go through the canonical
+  converter.** Pasting markdown into the editor, "Copy as markdown", the AI title
+  generator, and the AI-chat markdown renderer all now use
+  `@docmost/prosemirror-markdown` (via its new `browser` entry — native
+  `DOMParser`, no jsdom in the client bundle) instead of the hand-written
+  `marked`/`turndown` markdown layer in `editor-ext`, which was **deleted**. As a
+  result, pasting canonical markdown (`^[…]` footnotes, `<!--img …-->`,
+  `> [!type]` callouts, `$…$` math, `==…==` highlight, standalone `<!--subpages-->`
+  comments) now produces the SAME nodes the server import produces for the same
+  text. Chat/reasoning markdown now renders through the editor schema (list items
+  are wrapped in `<p>`; CSS keeps them tight). (#347)
+
 - **Enabling a public share no longer auto-shares the whole sub-tree.** Turning
   a page "Shared to web" now defaults to the page alone; descendant pages become
   public only when you explicitly turn on the dedicated "Include sub-pages"
@@ -169,6 +344,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **A chat with one malformed message part no longer 500s on every turn, and a
+  failed send no longer duplicates the user's message.** Incoming client parts
+  are now whitelisted to `text` (a forged tool-result part can no longer reach
+  the persisted history or the model context), and the turn is converted BEFORE
+  the user row is inserted, so a mid-flight failure cannot leave a duplicate
+  user row that a retry then compounds. A single part that still fails to convert
+  degrades to a `[tool context omitted]` marker on that one row instead of
+  bricking the whole chat. (#489)
+- **A transport drop to an external MCP server now heals within the same turn.**
+  On an undici transport error, a read-only MCP tool reconnects its server and
+  retries once within the run; a write is never auto-retried (it may already have
+  applied). One flapping server no longer nulls the shared client cache, so other
+  servers' cached clients are untouched. The SSE transport also gets a raised
+  body-timeout so a legitimate >1-min idle between the model's tool calls no
+  longer breaks a long-lived SSE socket (new `AI_MCP_SSE_BODY_TIMEOUT_MS`, default
+  10 min; see `.env.example`). (#489)
+
 - **The server no longer runs out of heap during long autonomous agent runs.** A
   new pnpm patch on `ai@6.0.134` stops the SDK from building a cumulative
   snapshot of the ENTIRE turn text on every streamed text-delta when no output
@@ -177,6 +369,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 +478,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"]

apps/client/package.json

@@ -21,6 +21,7 @@
     "@atlaskit/pragmatic-drag-and-drop-live-region": "1.3.4",
     "@casl/react": "5.0.1",
     "@docmost/editor-ext": "workspace:*",
+    "@docmost/prosemirror-markdown": "workspace:*",
     "@excalidraw/excalidraw": "0.18.0-3a5ef40",
     "@mantine/core": "8.3.18",
     "@mantine/dates": "8.3.18",

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

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

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

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

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

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

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

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

apps/client/src/features/ai-chat/components/ai-chat.module.css

@@ -55,6 +55,15 @@
     padding-inline-start: 1.4em;
 }
 
+/* The canonical converter renders list items through the editor schema, which
+   wraps each item's content in a <p> (listItem content is `paragraph+`). Drop
+   that paragraph's block margin so list items render TIGHT (no extra vertical
+   gap), matching the previous marked output — same rule already applied to
+   table cells above (issue #347). */
+.markdown li p {
+    margin: 0;
+}
+
 /* GFM tables in assistant markdown. The chat lives in a NARROW side panel, so a
    wide LLM table must scroll horizontally instead of collapsing its columns:
    `.markdown` sets `word-break: break-word`, which (with the default table
@@ -172,6 +181,14 @@
     margin: 0 0 4px;
 }
 
+/* Same as `.markdown li p` above: the canonical converter wraps every list
+   item's content in a <p>, so without this each reasoning-panel list item would
+   pick up `.reasoningText p`'s 4px bottom margin and render too loose. Drop it
+   so Reasoning-panel lists stay tight, mirroring the pre-#347 marked output. */
+.reasoningText li p {
+    margin: 0;
+}
+
 .inputWrapper {
     flex: 0 0 auto;
     padding-top: var(--mantine-spacing-xs);

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/services/ai-chat-service.ts

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

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

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

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

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

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

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

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

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

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

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

apps/client/src/features/ai-chat/utils/collapse-blank-lines.test.ts

@@ -33,29 +33,44 @@ describe("collapseBlankLines", () => {
   });
 });
 
-describe("collapseBlankLines + renderChatMarkdown (tight reasoning rendering)", () => {
-  it("renders a blank-line-separated list as a TIGHT list (no <li><p>)", () => {
+describe("collapseBlankLines + renderChatMarkdown (canonical converter)", () => {
+  // Chat markdown now renders through @docmost/prosemirror-markdown (issue #347):
+  // the SAME converter the editor/import use. Its list items are schema-shaped —
+  // each <li>'s content is wrapped in a <p> (listItem content is `paragraph+`) —
+  // so the HTML always carries `<li><p>…</p></li>` regardless of blank-line
+  // looseness in the source (the converter has no tight/loose distinction). The
+  // visual tightness that `collapseBlankLines` used to buy is now provided by
+  // CSS (`.markdown li p { margin: 0 }`), not the HTML shape.
+  it("renders a blank-line-separated bullet list as a real <ul> list", () => {
     const loose =
       "Intro paragraph.\n\n- item one\n\n- item two\n\n- item three";
     const html = renderChatMarkdown(collapseBlankLines(loose), {});
-    // Tight list: each <li> holds the text directly, not wrapped in a <p>.
-    expect(html).toContain("<li>item one</li>");
-    expect(html).not.toContain("<li><p>");
-    // The list still parses as a list after the paragraph (not a paragraph+<br>).
+    // Clean, un-namespaced HTML (DOMSerializer, not XMLSerializer) — no xmlns.
     expect(html).toContain("<ul>");
+    expect(html).not.toMatch(/<ul[^>]*xmlns/);
+    // The item text is present (inside the schema's <li><p> wrapper).
+    expect(html).toContain("item one");
+    // The intro paragraph renders as its own paragraph before the list.
     expect(html).toContain("<p>Intro paragraph.</p>");
   });
 
-  it("renders an ordered list (1. 2.) as tight after collapsing", () => {
+  it("renders an ordered list (1. 2.) as a real <ol> list", () => {
     const loose = "Intro.\n\n1. first\n\n2. second";
     const html = renderChatMarkdown(collapseBlankLines(loose), {});
     expect(html).toContain("<ol>");
-    expect(html).toContain("<li>first</li>");
-    expect(html).not.toContain("<li><p>");
+    expect(html).not.toMatch(/<ol[^>]*xmlns/);
+    expect(html).toContain("first");
+    expect(html).toContain("second");
   });
 
-  it("the loose source WOULD render <li><p> without collapsing (control)", () => {
+  it("wraps list-item content in <p> (schema shape; tightness is CSS)", () => {
+    // The canonical converter always wraps a list item's content in a paragraph,
+    // whether or not the source had blank lines between items.
     const loose = "- a\n\n- b";
     expect(renderChatMarkdown(loose, {})).toContain("<li><p>");
+    // And a "tight" source produces the identical wrapping (no distinction).
+    expect(renderChatMarkdown(collapseBlankLines(loose), {})).toContain(
+      "<li><p>",
+    );
   });
 });

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

@@ -23,6 +23,89 @@ 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",
+    );
+  });
+
+  // #488 commit 5: the #487 concurrency-gate / supersede 409s. FULL real bodies:
+  // a ConflictException(object) whose response is serialized verbatim, carrying a
+  // `code` and statusCode 409. Each must classify to a human text, not raw JSON.
+  it("classifies A_RUN_ALREADY_ACTIVE (409) as already-answering, not raw JSON", () => {
+    const body =
+      '{"message":"A run is already active for this chat","code":"A_RUN_ALREADY_ACTIVE","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe(
+      "The agent is already answering",
+    );
+    // Never leaks the raw code as the detail.
+    expect(describeChatError(body, t).detail).not.toContain("A_RUN_ALREADY_ACTIVE");
+  });
+
+  it("classifies SUPERSEDE_TARGET_MISMATCH (409) as run-changed", () => {
+    // Real server body shape: the current run id is `activeRunId` (NOT `runId`) —
+    // see ai-chat.controller.ts. describeChatError classifies off `code` only.
+    const body =
+      '{"message":"active run does not match the supersede target","code":"SUPERSEDE_TARGET_MISMATCH","activeRunId":"run-x","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe(
+      "Couldn't interrupt — the run changed",
+    );
+  });
+
+  it("classifies SUPERSEDE_TIMEOUT (409) as couldn't-interrupt-in-time", () => {
+    const body =
+      '{"message":"the run did not settle within the supersede window","code":"SUPERSEDE_TIMEOUT","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe("Couldn't interrupt in time");
+  });
+
+  it("classifies SUPERSEDE_INVALID (409) as couldn't-interrupt-that-run", () => {
+    const body =
+      '{"message":"supervise requires chatId","code":"SUPERSEDE_INVALID","statusCode":409}';
+    expect(describeChatError(body, t).title).toBe(
+      "Couldn't interrupt that run",
+    );
+  });
+
+  it("ORDER GUARD: A_RUN_ALREADY_ACTIVE wins over any generic status branch", () => {
+    // Even though the body could superficially look 4xx-ish, the code branch runs
+    // first, so it is never mislabeled by a generic status heading.
+    const body =
+      '{"message":"conflict","code":"A_RUN_ALREADY_ACTIVE","statusCode":409}';
+    const view = describeChatError(body, t);
+    expect(view.title).not.toBe("Something went wrong");
+    expect(view.title).not.toBe("AI provider not configured");
+  });
+
+  it("classifies a token-degeneration abort under the SAME 'Response stopped.' marker the live view shows (#495)", () => {
+    // The exact reason the server persists in metadata.error on a degeneration
+    // abort (ai-chat.service OUTPUT_DEGENERATION_ERROR). Live, this event shows
+    // the neutral "Response stopped." notice; the persisted banner MUST match it
+    // so live and refetch never disagree.
+    const view = describeChatError(
+      "Output degeneration detected (repeated token loop)",
+      t,
+    );
+    expect(view.title).toBe("Response stopped.");
+    expect(view.detail).toBe(
+      "The answer was stopped automatically because the model fell into a repeated output loop.",
+    );
+    // Regression guard: it must NOT fall through to the generic heading.
+    expect(view.title).not.toBe("Something went wrong");
+  });
+
   it("classifies a dropped connection (ECONNRESET) as a lost-connection error", () => {
     expect(
       describeChatError("Cannot connect to API: read ECONNRESET", t).title,

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

@@ -24,6 +24,75 @@ 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.",
+      ),
+    };
+  }
+
+  // #488 commit 5: the #487 concurrency-gate / supersede 409s. These arrive as a
+  // ConflictException(object) body carrying a `code` (and statusCode 409). They
+  // MUST be classified by `code` STRICTLY BEFORE any generic status branch, or the
+  // user sees the raw JSON `{"code":"A_RUN_ALREADY_ACTIVE",…}`. The code strings
+  // are the real #487 server contract (ai-chat.controller.ts) — do not invent.
+  if (/"code"\s*:\s*"A_RUN_ALREADY_ACTIVE"/.test(msg)) {
+    return {
+      title: t("The agent is already answering"),
+      detail: t(
+        "This chat already has a run in progress. Wait for it to finish, or interrupt it and send now.",
+      ),
+    };
+  }
+  if (/"code"\s*:\s*"SUPERSEDE_TARGET_MISMATCH"/.test(msg)) {
+    return {
+      title: t("Couldn't interrupt — the run changed"),
+      detail: t(
+        "The run you tried to interrupt is no longer the active one. Check the latest answer and try again.",
+      ),
+    };
+  }
+  if (/"code"\s*:\s*"SUPERSEDE_TIMEOUT"/.test(msg)) {
+    return {
+      title: t("Couldn't interrupt in time"),
+      detail: t(
+        "The previous run didn't stop in time. Nothing was sent — try sending again.",
+      ),
+    };
+  }
+  if (/"code"\s*:\s*"SUPERSEDE_INVALID"/.test(msg)) {
+    return {
+      title: t("Couldn't interrupt that run"),
+      detail: t(
+        "The run to interrupt doesn't belong to this chat. Reload and try again.",
+      ),
+    };
+  }
+
+  // Our own token-degeneration abort (#444): the server aborts a runaway
+  // repetition loop and persists this exact reason in metadata.error. LIVE, the
+  // same abort surfaces as the neutral "Response stopped." notice (the client
+  // cannot tell it from a manual Stop mid-stream), so the persisted banner must
+  // read the SAME "Response stopped." marker — otherwise the live view and a
+  // later refetch show two different texts for one event. The detail explains the
+  // loop-guard cause without contradicting the shared heading.
+  if (/output degeneration detected|repeated token loop/i.test(msg)) {
+    return {
+      title: t("Response stopped."),
+      detail: t(
+        "The answer was stopped automatically because the model fell into a repeated output loop.",
+      ),
+    };
+  }
+
   if (/"statusCode"\s*:\s*403\b/.test(msg)) {
     return {
       title: t("AI chat is disabled"),

apps/client/src/features/ai-chat/utils/markdown.ts

@@ -1,6 +1,37 @@
-import { markdownToHtml } from "@docmost/editor-ext";
+import {
+  markdownToProseMirrorSync,
+  docmostExtensions,
+} from "@docmost/prosemirror-markdown/browser";
+import { getSchema } from "@tiptap/core";
+import { Node as PMNode, DOMSerializer } from "@tiptap/pm/model";
 import DOMPurify from "dompurify";
 
+// The Docmost editor schema, built once. Chat markdown is rendered through the
+// SAME schema the editor/import use (issue #347), so chat output matches how the
+// page would render the same markdown.
+const chatSchema = getSchema(docmostExtensions);
+
+/**
+ * Markdown -> HTML for chat display, via the canonical converter. We serialize
+ * the ProseMirror doc with `DOMSerializer` into a real element and read its
+ * `innerHTML` (rather than `@tiptap/html`'s `generateHTML`, whose browser path
+ * uses `XMLSerializer` and stamps a `xmlns` on every block) so the markup is
+ * clean HTML. `li > p` wrapping is inherent to the schema (listItem content is
+ * `paragraph+`); the chat CSS zeroes those paragraph margins so lists still
+ * render tight.
+ */
+function markdownToChatHtml(markdown: string): string {
+  const doc = markdownToProseMirrorSync(markdown);
+  const node = PMNode.fromJSON(chatSchema, doc);
+  const div = document.createElement("div");
+  DOMSerializer.fromSchema(chatSchema).serializeFragment(
+    node.content,
+    { document },
+    div,
+  );
+  return div.innerHTML;
+}
+
 export interface RenderChatMarkdownOptions {
   /**
    * Neutralize INTERNAL links so they render as inert text (no `href`/`target`).
@@ -63,22 +94,32 @@ function neutralizeInternalLinksHook(node: Element): void {
 
 /**
  * Render AI markdown to sanitized HTML for read-only display. We reuse the
- * app's `markdownToHtml` (the same `marked` pipeline used for paste/import) so
- * chat output matches the editor's markdown flavor, then sanitize with
- * DOMPurify — LLM output is untrusted, so it must never reach the DOM unsanitized.
+ * canonical converter (issue #347): markdown -> ProseMirror JSON (the SAME
+ * `markdownToProseMirrorSync` the editor paste/import path uses, so chat output
+ * matches the editor's markdown flavor) -> HTML via `markdownToChatHtml`
+ * (DOMSerializer), then sanitize with DOMPurify — LLM output is untrusted, so it
+ * must never reach the DOM unsanitized.
  *
- * `markdownToHtml` can return `string | Promise<string>` (it has async marked
- * extensions registered). In practice plain chat markdown resolves
- * synchronously, but we guard the Promise case by returning a safe empty string
- * for that branch (the caller renders the raw text fallback instead).
+ * Stays SYNCHRONOUS: both callers render inside React (a memo and a useMemo),
+ * so the whole pipeline must resolve without awaiting. The converter's sync
+ * entry makes that possible; on any conversion error we return "" so the caller
+ * falls back to raw text (the same fallback the old Promise-guard produced).
  */
 export function renderChatMarkdown(
   markdown: string,
   options: RenderChatMarkdownOptions = {},
 ): string {
   if (!markdown) return "";
-  const html = markdownToHtml(markdown);
-  if (typeof html !== "string") return "";
+  let html: string;
+  try {
+    // markdown -> canonical PM JSON -> HTML (native DOMParser in the browser;
+    // jsdom is never bundled — see @docmost/prosemirror-markdown/browser).
+    html = markdownToChatHtml(markdown);
+  } catch {
+    // Malformed/unsupported markdown must not crash the chat render; fall back
+    // to raw text (empty return -> caller shows the plain-text branch).
+    return "";
+  }
 
   if (!options.neutralizeInternalLinks) {
     // Internal chat: unchanged behavior, no hook registered.

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

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

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

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

apps/client/src/features/editor/extensions/markdown-clipboard.paste.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from "vitest";
+import { Editor } from "@tiptap/core";
+import { Document } from "@tiptap/extension-document";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Text } from "@tiptap/extension-text";
+import { Bold } from "@tiptap/extension-bold";
+import { Italic } from "@tiptap/extension-italic";
+import { MarkdownClipboard } from "./markdown-clipboard";
+
+/**
+ * Integration coverage for the async `handlePaste` seam (issue #347). The paste
+ * conversion moved to `@docmost/prosemirror-markdown`'s browser entry, whose
+ * `markdownToProseMirror` is async — so `handlePaste` captures the range, claims
+ * the event (returns true), and dispatches the insert on the next microtask.
+ * These tests drive that path end to end on a minimal schema (a plain-markdown
+ * paste whose converted nodes fit paragraph/text/bold/italic), asserting the
+ * text lands with the right marks and that the raw markdown syntax is consumed
+ * (recognized as markdown, not inserted literally).
+ */
+
+function makeEditor() {
+  const element = document.createElement("div");
+  document.body.appendChild(element);
+  return new Editor({
+    element,
+    extensions: [
+      Document,
+      Paragraph,
+      Text,
+      Bold,
+      Italic,
+      MarkdownClipboard.configure({ transformPastedText: true }),
+    ],
+    content: { type: "doc", content: [{ type: "paragraph" }] },
+  });
+}
+
+// Locate the markdownClipboard plugin and invoke its handlePaste directly with a
+// synthetic clipboard event (jsdom has no real paste pipeline). The plugin's
+// handlePaste closes over the extension `this`, so calling it off the plugin
+// props preserves `this.editor`/`this.options`.
+function paste(editor: Editor, text: string): boolean {
+  const view = editor.view;
+  const plugin = view.state.plugins.find(
+    (p: any) => p.props && p.spec?.key,
+  ) as any;
+  const event = {
+    clipboardData: {
+      getData: (type: string) => (type === "text/plain" ? text : ""),
+    },
+  } as unknown as ClipboardEvent;
+  // Find the specific handlePaste that belongs to the markdown clipboard plugin.
+  const md = view.state.plugins.find(
+    (p: any) => typeof p.props?.handlePaste === "function",
+  ) as any;
+  return md.props.handlePaste(view, event, view.state.selection.content());
+}
+
+// Flush the microtask queue so the async .then() dispatch runs.
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+describe("MarkdownClipboard handlePaste (async md -> PM)", () => {
+  it("converts a plain-markdown paste with bold/italic into marked text", async () => {
+    const editor = makeEditor();
+    const claimed = paste(editor, "hello **bold** and *italic*");
+    // The paste is claimed synchronously (async insert follows).
+    expect(claimed).toBe(true);
+    await flush();
+
+    const json = editor.getJSON();
+    const text = JSON.stringify(json);
+    // The raw markdown asterisks are consumed (recognized), not inserted literally.
+    expect(editor.getText()).not.toContain("**");
+    expect(editor.getText()).toContain("bold");
+    expect(editor.getText()).toContain("italic");
+    // The bold/italic marks materialized.
+    expect(text).toContain('"bold"');
+    expect(text).toContain('"italic"');
+    editor.destroy();
+  });
+
+  it("recognizes a bullet list paste as list structure (not literal '-')", async () => {
+    // A bullet list is not representable in this minimal schema, so the converter
+    // output would fail PMNode.fromJSON and the catch inserts raw text. Use a
+    // paste whose nodes DO fit the schema to assert the happy path instead: two
+    // paragraphs separated by a blank line.
+    const editor = makeEditor();
+    paste(editor, "first para\n\nsecond para");
+    await flush();
+    const json = editor.getJSON() as any;
+    const paras = (json.content || []).filter(
+      (n: any) => n.type === "paragraph",
+    );
+    // Two paragraphs materialized from the blank-line-separated markdown.
+    expect(paras.length).toBeGreaterThanOrEqual(2);
+    expect(editor.getText()).toContain("first para");
+    expect(editor.getText()).toContain("second para");
+    editor.destroy();
+  });
+
+  it("falls back to raw text when conversion yields nodes the schema lacks", async () => {
+    // `# heading` converts to a `heading` node absent from this minimal schema,
+    // so PMNode.fromJSON throws and the catch re-inserts the raw text — the user
+    // never loses their clipboard content.
+    const editor = makeEditor();
+    paste(editor, "# a heading line");
+    await flush();
+    // Content is preserved (either as heading text or literal), never dropped.
+    expect(editor.getText()).toContain("a heading line");
+    editor.destroy();
+  });
+});
+
+// The async seam captures the target range synchronously, then replaces on the
+// next microtask. If the document changed under it between capture and resolve
+// (impossible in prod — same microtask — but pinned here), BOTH the success
+// (replaceRange) and the fail-open (insertText) branches must fall back to the
+// LIVE selection rather than a stale absolute range, so neither clobbers content
+// nor throws a RangeError. We force the mid-flight change by dispatching a
+// doc-mutating transaction AFTER the synchronous claim but BEFORE flushing the
+// microtask that runs the `.then`/`.catch`.
+describe("MarkdownClipboard handlePaste — doc-changed-mid-flight guard", () => {
+  // Replace the whole doc with one paragraph of `text` (synchronous dispatch).
+  // An empty string yields an empty paragraph (a text node may not be empty).
+  function seedContent(editor: Editor, text: string) {
+    editor.commands.setContent({
+      type: "doc",
+      content: [
+        text
+          ? { type: "paragraph", content: [{ type: "text", text }] }
+          : { type: "paragraph" },
+      ],
+    });
+  }
+
+  it("success branch: mid-flight doc change routes the paste to the LIVE selection, never the stale range (clobber-proving)", async () => {
+    // The paste captures a NON-EMPTY range {1,5} (over "AAAA"). Then, before the
+    // async resolve, the doc GROWS ("MARKER" inserted at the start) and the cursor
+    // is parked at the doc END. The captured {1,5} is now stale and points INTO
+    // "MARKER". A WORKING guard replaces at the live (end) selection → MARKER is
+    // untouched. A BROKEN guard replaces the stale {1,5} → it erases the first
+    // characters of MARKER (this is what a zero-width `from==to` range could never
+    // reveal, which is why the earlier version was vacuous).
+    const editor = makeEditor();
+    seedContent(editor, "AAAABBBB");
+    editor.commands.setTextSelection({ from: 1, to: 5 }); // captured range = {1,5}
+    const claimed = paste(editor, "hello **bold**");
+    expect(claimed).toBe(true);
+
+    // Mid-flight: grow the doc and move the cursor to a KNOWN-safe end position.
+    editor.view.dispatch(editor.view.state.tr.insertText("MARKER", 1));
+    const end = editor.state.doc.content.size;
+    editor.commands.setTextSelection({ from: end, to: end });
+    await flush();
+
+    const text = editor.getText();
+    // MARKER intact only if the guard used the live selection, not the stale range.
+    expect(text).toContain("MARKER");
+    expect(text).toContain("bold");
+    expect(text).not.toContain("**");
+    editor.destroy();
+  });
+
+  it("fail-open branch: a mid-flight doc SHRINK makes the stale `to` out of bounds — the guard must avoid a RangeError (throw-proving)", async () => {
+    // The paste captures a range {1,9} over an 8-char paragraph, then the
+    // conversion FAILS (`# heading` -> a heading node the minimal schema lacks,
+    // so PMNode.fromJSON throws -> the fail-open catch runs). Before the reject,
+    // the doc is SHRUNK to an empty paragraph, so the captured `to` (9) is now far
+    // past the doc's end. A WORKING guard inserts the raw text at the live (valid)
+    // selection → "raw heading" lands. A BROKEN guard does insertText(md, 1, 9) on
+    // a size-2 doc → RangeError, so the dispatch never runs and "raw heading" is
+    // absent (the assertion reddens). A zero-width/growing-doc setup could never
+    // push `to` out of bounds, which is why the earlier version was vacuous.
+    const editor = makeEditor();
+    seedContent(editor, "AAAABBBB");
+    editor.commands.setTextSelection({ from: 1, to: 9 }); // captured range = {1,9}
+    paste(editor, "# raw heading");
+
+    // Mid-flight: shrink the doc so the captured `to` = 9 is now out of bounds.
+    seedContent(editor, "");
+    await flush();
+
+    const text = editor.getText();
+    // Raw text lands (via the live selection) only if the guard avoided the
+    // stale, now-out-of-bounds range.
+    expect(text).toContain("raw heading");
+    editor.destroy();
+  });
+
+  it("two pastes in flight: neither payload is lost (no data loss)", async () => {
+    // Prod-unreachable (two paste events are separate macrotasks, and each
+    // conversion resolves on a microtask before the next), but pinned here: when
+    // both resolve back-to-back, the second sees the changed doc and inserts at
+    // the live selection the first left — so the two payloads may INTERLEAVE, but
+    // neither is dropped. We assert no data loss, not contiguity.
+    const editor = makeEditor();
+    paste(editor, "alphaword");
+    paste(editor, "betaword");
+    await flush();
+    const text = editor.getText();
+    // Neither payload fully dropped (interleaving may split one of them).
+    expect(text).toContain("alpha");
+    expect(text).toContain("beta");
+    editor.destroy();
+  });
+});

apps/client/src/features/editor/extensions/markdown-clipboard.test.ts

@@ -1,5 +1,12 @@
 import { describe, it, expect } from "vitest";
-import { htmlToMarkdown } from "@docmost/editor-ext";
+// Markdown conversion now goes through the canonical package's BROWSER entry
+// (issue #347): the same converter the server import/export uses, resolved via
+// the `browser` exports condition so it runs on the native `DOMParser` (the
+// client jsdom vitest env provides one) with jsdom never bundled.
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirrorSync,
+} from "@docmost/prosemirror-markdown/browser";
 import {
   normalizeTableColumnWidths,
   classifyClipboardSelection,
@@ -175,10 +182,13 @@ describe("classifyClipboardSelection", () => {
 
 // Output-level tests for the table clipboard regression: copying a table must
 // yield a real GFM pipe table, NOT one-value-per-line concatenated cells.
-// These exercise the actual markdown produced by htmlToMarkdown (the same
-// serializer step the clipboardTextSerializer runs), so they pin the OUTPUT
-// shape that the classifier-flag tests above do not cover.
-describe("table clipboard markdown output (htmlToMarkdown)", () => {
+// These exercise the actual markdown produced by convertProseMirrorToMarkdown —
+// the same serializer step the clipboardTextSerializer now runs (issue #347) —
+// so they pin the OUTPUT shape that the classifier-flag tests above do not cover.
+// Input is ProseMirror JSON (what the copied slice serializes to), matching the
+// clipboardTextSerializer's new call: it wraps the slice content in a synthetic
+// `doc` (and the bare-rows case in a `table`) and calls the converter.
+describe("table clipboard markdown output (convertProseMirrorToMarkdown)", () => {
   // Trim each line and drop blanks so structural assertions are whitespace-robust.
   function lines(md: string): string[] {
     return md
@@ -188,10 +198,10 @@ describe("table clipboard markdown output (htmlToMarkdown)", () => {
   }
 
   // A GFM separator row like "| --- | --- |" (any number of columns), tolerant
-  // of the padding turndown emits.
+  // of the padding the serializer emits.
   function isSeparatorRow(line: string): boolean {
     const compact = line.replace(/\s+/g, "");
-    return /^\|(?:-{3,}\|)+$/.test(compact);
+    return /^\|(?::?-{2,}:?\|)+$/.test(compact);
   }
 
   // Split a pipe-delimited row into trimmed cell values.
@@ -203,42 +213,33 @@ describe("table clipboard markdown output (htmlToMarkdown)", () => {
       .map((c) => c.trim());
   }
 
-  it("serializes a header-less partial cell selection (bare rows) as a valid GFM pipe table", () => {
-    // Mirror the serializer's `wrapBareRows` branch exactly: bare <tr> nodes are
-    // wrapped in <table><tbody> and htmlToMarkdown(div.innerHTML) is called.
-    // See markdown-clipboard.ts clipboardTextSerializer:
-    //   const table = document.createElement("table");
-    //   const tbody = document.createElement("tbody");
-    //   tbody.appendChild(fragment); table.appendChild(tbody);
-    //   div.appendChild(table);
-    //   return htmlToMarkdown(div.innerHTML);
-    const div = document.createElement("div");
-    const table = document.createElement("table");
-    const tbody = document.createElement("tbody");
-    for (const [c1, c2] of [
-      ["a", "b"],
-      ["c", "d"],
-    ]) {
-      const tr = document.createElement("tr");
-      const td1 = document.createElement("td");
-      td1.textContent = c1;
-      const td2 = document.createElement("td");
-      td2.textContent = c2;
-      tr.appendChild(td1);
-      tr.appendChild(td2);
-      tbody.appendChild(tr);
-    }
-    table.appendChild(tbody);
-    div.appendChild(table);
+  const cell = (t: string) => ({
+    type: "tableCell",
+    content: [{ type: "paragraph", content: [{ type: "text", text: t }] }],
+  });
+  const headerCell = (t: string) => ({
+    type: "tableHeader",
+    content: [{ type: "paragraph", content: [{ type: "text", text: t }] }],
+  });
+  const row = (nodes: any[]) => ({ type: "tableRow", content: nodes });
 
-    const md = htmlToMarkdown(div.innerHTML);
+  it("serializes a header-less partial cell selection (bare rows) as a valid GFM pipe table", () => {
+    // Mirror the serializer's `wrapBareRows` branch: bare tableRow nodes are
+    // wrapped in a synthetic `table` and convertProseMirrorToMarkdown is called
+    // (see markdown-clipboard.ts clipboardTextSerializer).
+    const rows = [
+      row([cell("a"), cell("b")]),
+      row([cell("c"), cell("d")]),
+    ];
+    const md = convertProseMirrorToMarkdown({
+      type: "doc",
+      content: [{ type: "table", content: rows }],
+    });
     const ls = lines(md);
 
-    // Valid GFM: a header/data separator row is present (an empty header is
-    // synthesized by the GFM turndown plugin for a header-less table — fine).
+    // Valid GFM: a header/data separator row is present.
     expect(ls.some(isSeparatorRow)).toBe(true);
-    // NOT the old broken "one value per line" shape: every line is pipe-delimited
-    // and no line is a bare cell value on its own.
+    // NOT the old broken "one value per line" shape: every line is pipe-delimited.
     expect(ls.every((l) => l.includes("|"))).toBe(true);
     expect(md).not.toMatch(/^\s*(a|b|c|d)\s*$/m);
     // The cell values land in real pipe-delimited data rows.
@@ -248,39 +249,21 @@ describe("table clipboard markdown output (htmlToMarkdown)", () => {
   });
 
   it("serializes a whole table with a header row as a proper GFM table (headline regression)", () => {
-    // Mirror the serializer's non-wrap branch: the full <table> node is appended
-    // directly (div.appendChild(fragment)) and htmlToMarkdown(div.innerHTML) runs.
-    const div = document.createElement("div");
-    const table = document.createElement("table");
-
-    const thead = document.createElement("thead");
-    const headerRow = document.createElement("tr");
-    for (const h of ["Name", "Age"]) {
-      const th = document.createElement("th");
-      th.textContent = h;
-      headerRow.appendChild(th);
-    }
-    thead.appendChild(headerRow);
-    table.appendChild(thead);
-
-    const tbody = document.createElement("tbody");
-    for (const [name, age] of [
-      ["Alice", "30"],
-      ["Bob", "25"],
-    ]) {
-      const tr = document.createElement("tr");
-      const td1 = document.createElement("td");
-      td1.textContent = name;
-      const td2 = document.createElement("td");
-      td2.textContent = age;
-      tr.appendChild(td1);
-      tr.appendChild(td2);
-      tbody.appendChild(tr);
-    }
-    table.appendChild(tbody);
-    div.appendChild(table);
-
-    const md = htmlToMarkdown(div.innerHTML);
+    // Mirror the serializer's non-wrap branch: the full `table` node is the
+    // slice content and convertProseMirrorToMarkdown runs on it.
+    const md = convertProseMirrorToMarkdown({
+      type: "doc",
+      content: [
+        {
+          type: "table",
+          content: [
+            row([headerCell("Name"), headerCell("Age")]),
+            row([cell("Alice"), cell("30")]),
+            row([cell("Bob"), cell("25")]),
+          ],
+        },
+      ],
+    });
     const ls = lines(md);
 
     // Proper GFM structure: separator row + all rows pipe-delimited.
@@ -296,3 +279,146 @@ describe("table clipboard markdown output (htmlToMarkdown)", () => {
     expect(md).not.toMatch(/^\s*(Name|Age|Alice|Bob|30|25)\s*$/m);
   });
 });
+
+// #347 acceptance: pasting CANONICAL markdown yields the SAME nodes the server
+// import produces for the same text. The paste path calls markdownToProseMirror
+// (the package browser entry) — the identical converter the server import uses —
+// so asserting the converter (via the browser entry, on the native DOMParser)
+// recognizes each canon form pins the paste-parity guarantee. These forms were
+// NOT recognized by the old editor-ext marked layer the paste used before.
+describe("canonical markdown paste recognition (browser entry parity)", () => {
+  // Collect every node type present in a doc (recursively).
+  const collectTypes = (n: any, set = new Set<string>()): Set<string> => {
+    if (!n || typeof n !== "object") return set;
+    if (n.type) set.add(n.type);
+    if (Array.isArray(n.content)) n.content.forEach((c) => collectTypes(c, set));
+    return set;
+  };
+  const findNode = (n: any, type: string): any => {
+    if (!n || typeof n !== "object") return undefined;
+    if (n.type === type) return n;
+    if (Array.isArray(n.content)) {
+      for (const c of n.content) {
+        const hit = findNode(c, type);
+        if (hit) return hit;
+      }
+    }
+    return undefined;
+  };
+  const allText = (n: any): string => {
+    if (!n || typeof n !== "object") return "";
+    if (typeof n.text === "string") return n.text;
+    if (Array.isArray(n.content)) return n.content.map(allText).join("");
+    return "";
+  };
+
+  it("^[…] inline footnote -> footnoteReference + footnotesList", () => {
+    const doc = markdownToProseMirrorSync("Body^[a note here].");
+    const types = collectTypes(doc);
+    expect(types.has("footnoteReference")).toBe(true);
+    expect(types.has("footnotesList")).toBe(true);
+    expect(types.has("footnoteDefinition")).toBe(true);
+  });
+
+  it('<!--img {…}--> attached image comment -> image with align', () => {
+    const doc = markdownToProseMirrorSync(
+      '![alt](/files/x.png) <!--img {"align":"left"}-->',
+    );
+    const img = findNode(doc, "image");
+    expect(img).toBeTruthy();
+    expect(img.attrs?.align).toBe("left");
+    expect(img.attrs?.src).toBe("/files/x.png");
+  });
+
+  it("> [!type] Obsidian callout -> callout node with type", () => {
+    const doc = markdownToProseMirrorSync("> [!warning]\n> be careful");
+    const callout = findNode(doc, "callout");
+    expect(callout).toBeTruthy();
+    expect(callout.attrs?.type).toBe("warning");
+    expect(allText(callout)).toContain("be careful");
+  });
+
+  it("$…$ inline math -> mathInline node", () => {
+    const doc = markdownToProseMirrorSync("Euler: $e^{i\\pi}+1=0$ done");
+    const math = findNode(doc, "mathInline");
+    expect(math).toBeTruthy();
+    expect(math.attrs?.text).toContain("e^{i\\pi}");
+  });
+
+  it("==…== highlight -> highlight mark", () => {
+    const doc = markdownToProseMirrorSync("A ==marked== word");
+    const marked = findNode(doc, "text");
+    // The highlighted run carries a `highlight` mark somewhere in the doc.
+    const hasHighlight = (n: any): boolean => {
+      if (!n || typeof n !== "object") return false;
+      if (
+        n.type === "text" &&
+        (n.marks || []).some((m: any) => m.type === "highlight")
+      )
+        return true;
+      return Array.isArray(n.content) ? n.content.some(hasHighlight) : false;
+    };
+    expect(marked).toBeTruthy();
+    expect(hasHighlight(doc)).toBe(true);
+  });
+
+  it("<!--subpages--> standalone comment -> subpages node", () => {
+    const doc = markdownToProseMirrorSync("intro\n\n<!--subpages-->\n\nafter");
+    expect(collectTypes(doc).has("subpages")).toBe(true);
+  });
+});
+
+// #347 negatives: plain text carrying markdown-LIKE punctuation must NOT be
+// silently converted/mangled (currency, bare `==`, a `[^1]` reference form).
+describe("plain-text paste negatives (no phantom conversion)", () => {
+  const findNode = (n: any, type: string): any => {
+    if (!n || typeof n !== "object") return undefined;
+    if (n.type === type) return n;
+    if (Array.isArray(n.content)) {
+      for (const c of n.content) {
+        const hit = findNode(c, type);
+        if (hit) return hit;
+      }
+    }
+    return undefined;
+  };
+  const collectTypes = (n: any, set = new Set<string>()): Set<string> => {
+    if (!n || typeof n !== "object") return set;
+    if (n.type) set.add(n.type);
+    if (Array.isArray(n.content)) n.content.forEach((c) => collectTypes(c, set));
+    return set;
+  };
+  const allText = (n: any): string => {
+    if (!n || typeof n !== "object") return "";
+    if (typeof n.text === "string") return n.text;
+    if (Array.isArray(n.content)) return n.content.map(allText).join("");
+    return "";
+  };
+
+  it("currency `$5 and $10` is NOT turned into math", () => {
+    const doc = markdownToProseMirrorSync("It costs $5 and $10 total");
+    expect(findNode(doc, "mathInline")).toBeFalsy();
+    expect(allText(doc)).toContain("$5 and $10");
+  });
+
+  it("a lone `==` is NOT turned into a highlight", () => {
+    const doc = markdownToProseMirrorSync("compare a == b in code");
+    const hasHighlight = (n: any): boolean => {
+      if (!n || typeof n !== "object") return false;
+      if (
+        n.type === "text" &&
+        (n.marks || []).some((m: any) => m.type === "highlight")
+      )
+        return true;
+      return Array.isArray(n.content) ? n.content.some(hasHighlight) : false;
+    };
+    expect(hasHighlight(doc)).toBe(false);
+    expect(allText(doc)).toContain("== b");
+  });
+
+  it("a `[^1]` reference form (no `^[`) is NOT turned into a footnote", () => {
+    const doc = markdownToProseMirrorSync("see note [^1] for details");
+    expect(collectTypes(doc).has("footnoteReference")).toBe(false);
+    expect(allText(doc)).toContain("[^1]");
+  });
+});

apps/client/src/features/editor/extensions/markdown-clipboard.ts

@@ -1,15 +1,23 @@
 // adapted from: https://github.com/aguingand/tiptap-markdown/blob/main/src/extensions/tiptap/clipboard.js - MIT
 import { Extension } from "@tiptap/core";
 import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
-import { DOMParser, DOMSerializer, Fragment, Slice } from "@tiptap/pm/model";
+import { DOMParser, DOMSerializer, Fragment, Slice, Node as PMNode } from "@tiptap/pm/model";
 import { find } from "linkifyjs";
 import {
-  markdownToHtml,
-  htmlToMarkdown,
   canonicalizeFootnotes,
   FOOTNOTES_LIST_NAME,
   FOOTNOTE_REFERENCE_NAME,
 } from "@docmost/editor-ext";
+// Markdown <-> ProseMirror conversion now lives ONLY in the canonical
+// `@docmost/prosemirror-markdown` package (issue #347). The BROWSER entry uses
+// the native `DOMParser` for its HTML->DOM stage (jsdom stays out of the client
+// bundle) while producing the SAME nodes the server import does — so a paste of
+// canonical markdown (`^[…]`, `<!--img …-->`, `> [!type]`, `$…$`, `==…==`,
+// standalone comments) is recognized identically to import.
+import {
+  markdownToProseMirror,
+  convertProseMirrorToMarkdown,
+} from "@docmost/prosemirror-markdown/browser";
 import type { Schema } from "@tiptap/pm/model";
 
 export const MarkdownClipboard = Extension.create({
@@ -39,25 +47,24 @@ export const MarkdownClipboard = Extension.create({
               classifyClipboardSelection(topLevelNodes);
             if (!asMarkdown) return null;
 
-            const div = document.createElement("div");
-            const serializer = DOMSerializer.fromSchema(this.editor.schema);
-            const fragment = serializer.serializeFragment(slice.content);
-
+            // Convert the copied selection to Markdown through the canonical
+            // package (issue #347), the SAME serializer the server export uses,
+            // so a copied table/list matches the on-disk markdown form. The
+            // converter takes a ProseMirror `doc` JSON, so wrap the slice's
+            // top-level content in a synthetic doc.
+            const content = slice.content.toJSON() as any[];
             if (wrapBareRows) {
-              // A partial table cell-selection serializes to bare <tr> nodes
-              // (prosemirror-tables returns the whole `table` node only when the
-              // entire table is selected). Bare <tr> would be foster-parented
-              // away by the HTML parser inside htmlToMarkdown, so wrap them in
-              // <table><tbody> first for the GFM turndown rule to detect them.
-              const table = document.createElement("table");
-              const tbody = document.createElement("tbody");
-              tbody.appendChild(fragment);
-              table.appendChild(tbody);
-              div.appendChild(table);
-            } else {
-              div.appendChild(fragment);
+              // A partial table cell-selection serializes to bare `tableRow`
+              // nodes (prosemirror-tables yields the whole `table` node only for
+              // a full-table selection). The converter's table case expects a
+              // `table` wrapper, so wrap the bare rows in one — mirroring the old
+              // <table><tbody> wrap that the HTML->markdown step needed.
+              return convertProseMirrorToMarkdown({
+                type: "doc",
+                content: [{ type: "table", content }],
+              });
             }
-            return htmlToMarkdown(div.innerHTML);
+            return convertProseMirrorToMarkdown({ type: "doc", content });
           },
           handlePaste: (view, event, slice) => {
             if (!event.clipboardData) {
@@ -95,37 +102,115 @@ export const MarkdownClipboard = Extension.create({
               }
             }
 
-            const { tr } = view.state;
-            const { from, to } = view.state.selection;
+            const schema = this.editor.schema;
+            // Capture the target range NOW. markdownToProseMirror RETURNS A
+            // PROMISE (kept async only for the Node consumers' contract; the
+            // conversion pipeline itself is synchronous), so the actual replace
+            // happens on the next microtask. No user input can interleave a
+            // microtask, so the state is unchanged when we dispatch — but we
+            // still re-read the live state before replacing and, if the doc did
+            // change under us, fall back to the live selection rather than the
+            // captured (now-stale) range.
+            const from = view.state.selection.from;
+            const to = view.state.selection.to;
+            const startDoc = view.state.doc;
+            const md = text.replace(/\n+$/, "");
 
-            const parsed = markdownToHtml(text.replace(/\n+$/, ""));
-            const body = elementFromString(parsed);
-            normalizeTableColumnWidths(body);
+            void markdownToProseMirror(md)
+              .then((doc) => {
+                if (view.isDestroyed) return;
+                // Canonical PM-JSON -> HTML via the LIVE editor schema, then
+                // reuse the UNCHANGED downstream seam (normalizeTableColumnWidths
+                // + parseSlice + canonicalizePastedFootnotes). The JSON->HTML->
+                // JSON hop is lossless (same schema both directions); it lets the
+                // existing paste-insertion logic stay byte-identical — only the
+                // SOURCE of the markdown conversion changed (issue #347 guardrail:
+                // no converter logic in the client, only a call into the package).
+                const node = PMNode.fromJSON(schema, doc);
+                const div = document.createElement("div");
+                DOMSerializer.fromSchema(schema).serializeFragment(
+                  node.content,
+                  { document },
+                  div,
+                );
 
-            const parsedSlice = DOMParser.fromSchema(
-              this.editor.schema,
-            ).parseSlice(body, {
-              preserveWhitespace: true,
-            });
+                const body = elementFromString(div.innerHTML);
+                normalizeTableColumnWidths(body);
 
-            // A markdown paste builds its ProseMirror fragment directly (DOM ->
-            // parseSlice), bypassing the editor's footnoteSyncPlugin, which never
-            // reorders an existing list. So a pasted markdown block whose footnote
-            // definitions are out of order (or contains orphan defs) would be
-            // stored out of order. Canonicalize the self-contained pasted block so
-            // its footnotes come out reference-ordered, deduped and orphan-free
-            // (issue #228). See canonicalizePastedFootnotes for why this is scoped
-            // to whole-block pastes that carry their own footnotesList.
-            const contentNodes = canonicalizePastedFootnotes(
-              parsedSlice,
-              this.editor.schema,
-            );
+                const parsedSlice = DOMParser.fromSchema(schema).parseSlice(
+                  body,
+                  { preserveWhitespace: true },
+                );
 
-            tr.replaceRange(from, to, contentNodes);
-            const insertEnd = tr.mapping.map(from, 1);
-            tr.setSelection(TextSelection.near(tr.doc.resolve(Math.max(from, insertEnd - 2)), -1));
-            tr.setMeta('paste', true)
-            view.dispatch(tr);
+                // A markdown paste builds its ProseMirror fragment directly (DOM
+                // -> parseSlice), bypassing the editor's footnoteSyncPlugin, which
+                // never reorders an existing list. So a pasted markdown block whose
+                // footnote definitions are out of order (or contains orphan defs)
+                // would be stored out of order. Canonicalize the self-contained
+                // pasted block so its footnotes come out reference-ordered, deduped
+                // and orphan-free (issue #228). See canonicalizePastedFootnotes for
+                // why this is scoped to whole-block pastes that carry their own
+                // footnotesList.
+                const contentNodes = canonicalizePastedFootnotes(
+                  parsedSlice,
+                  schema,
+                );
+
+                // Target the captured range (normally still valid — same
+                // microtask). If the doc changed under us since capture, the
+                // captured absolute from/to are stale, so fall back to the live
+                // selection rather than StepMap-mapping the old range.
+                const tr = view.state.tr;
+                let mappedFrom = from;
+                let mappedTo = to;
+                if (view.state.doc !== startDoc) {
+                  // Defensive: if the doc changed under us, fall back to the
+                  // current selection rather than a stale absolute range.
+                  mappedFrom = view.state.selection.from;
+                  mappedTo = view.state.selection.to;
+                }
+                tr.replaceRange(mappedFrom, mappedTo, contentNodes);
+                const insertEnd = tr.mapping.map(mappedFrom, 1);
+                tr.setSelection(
+                  TextSelection.near(
+                    tr.doc.resolve(Math.max(mappedFrom, insertEnd - 2)),
+                    -1,
+                  ),
+                );
+                tr.setMeta("paste", true);
+                view.dispatch(tr);
+              })
+              .catch((err) => {
+                // Fail-open: a conversion error must not swallow the paste
+                // silently in a way that loses the text. We already claimed the
+                // event (returned true), so re-insert the raw text as a plain
+                // paragraph so the user never loses their clipboard content.
+                // Log it: this catch covers BOTH the converter and the success
+                // `.then` body (e.g. PMNode.fromJSON throwing on a schema drift
+                // between the canonical package and the live editor schema), so a
+                // silent degrade to raw text would otherwise be an invisible,
+                // non-reproducible regression ("my table pasted as text").
+                console.error(
+                  "markdown paste conversion failed, inserting raw text",
+                  err,
+                );
+                if (view.isDestroyed) return;
+                const tr = view.state.tr;
+                // Same guard the success path uses: if the doc changed under us
+                // since the range was captured (normally never — same microtask),
+                // the captured absolute from/to are stale and would throw a
+                // RangeError here (an unhandled rejection on a hot paste path).
+                // Fall back to the live selection instead of a stale range.
+                if (view.state.doc !== startDoc) {
+                  const sel = view.state.selection;
+                  tr.insertText(md, sel.from, sel.to);
+                } else {
+                  tr.insertText(md, from, to);
+                }
+                tr.setMeta("paste", true);
+                view.dispatch(tr);
+              });
+            // Claim the paste: we insert asynchronously above.
             return true;
           },
           // Strip trailing whitespace-only paragraphs from pasted content.

apps/client/src/features/editor/hooks/use-generate-page-title.test.tsx

@@ -33,10 +33,11 @@ vi.mock("@/lib/local-emitter.ts", () => ({
   default: { emit: (...args: unknown[]) => localEmitMock(...args) },
 }));
 
-// htmlToMarkdown just echoes the editor HTML so each test controls the markdown
-// purely via the fake page editor's getHTML().
-vi.mock("@docmost/editor-ext", () => ({
-  htmlToMarkdown: (html: string) => html,
+// convertProseMirrorToMarkdown echoes a marker carried on the fake editor's
+// getJSON() doc, so each test controls the markdown purely via the fake page
+// editor (issue #347: the hook now serializes editor JSON through the package).
+vi.mock("@docmost/prosemirror-markdown/browser", () => ({
+  convertProseMirrorToMarkdown: (doc: { __md?: string }) => doc?.__md ?? "",
 }));
 
 const notificationsShowMock = vi.fn();
@@ -53,10 +54,12 @@ import { useGeneratePageTitle } from "./use-generate-page-title.ts";
 
 // --- Test helpers -------------------------------------------------------------
 
-function makePageEditor(pageId: string, html = "<p>content</p>"): Editor {
+function makePageEditor(pageId: string, md = "content"): Editor {
   return {
     isDestroyed: false,
-    getHTML: () => html,
+    // The mocked convertProseMirrorToMarkdown reads `__md` back off this doc,
+    // so `md` is exactly the markdown the hook will send to the title service.
+    getJSON: () => ({ type: "doc", __md: md }),
     storage: { pageId },
   } as unknown as Editor;
 }

apps/client/src/features/editor/hooks/use-generate-page-title.ts

@@ -3,7 +3,7 @@ import { useMutation } from "@tanstack/react-query";
 import { useAtomValue } from "jotai";
 import { notifications } from "@mantine/notifications";
 import { useTranslation } from "react-i18next";
-import { htmlToMarkdown } from "@docmost/editor-ext";
+import { convertProseMirrorToMarkdown } from "@docmost/prosemirror-markdown/browser";
 import {
   pageEditorAtom,
   titleEditorAtom,
@@ -49,7 +49,9 @@ export function useGeneratePageTitle(pageId: string) {
     mutationFn: async () => {
       if (!pageEditor || pageEditor.isDestroyed) return;
 
-      const markdown = htmlToMarkdown(pageEditor.getHTML()).trim();
+      // Serialize the live editor content to markdown through the canonical
+      // converter (issue #347), matching the on-disk/export markdown form.
+      const markdown = convertProseMirrorToMarkdown(pageEditor.getJSON()).trim();
       if (!markdown) {
         notifications.show({ message: t("The note is empty"), color: "yellow" });
         return;

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

@@ -37,7 +37,7 @@ import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts
 import { PageWidthToggle } from "@/features/user/components/page-width-pref.tsx";
 import { Trans, useTranslation } from "react-i18next";
 import ExportModal from "@/components/common/export-modal";
-import { htmlToMarkdown } from "@docmost/editor-ext";
+import { convertProseMirrorToMarkdown } from "@docmost/prosemirror-markdown/browser";
 import {
   pageEditorAtom,
   yjsConnectionStatusAtom,
@@ -199,8 +199,9 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
 
   const handleCopyAsMarkdown = () => {
     if (!pageEditor) return;
-    const html = pageEditor.getHTML();
-    const markdown = htmlToMarkdown(html);
+    // Copy the page as canonical markdown through the shared converter (issue
+    // #347), so "Copy as markdown" matches the server export byte-for-byte.
+    const markdown = convertProseMirrorToMarkdown(pageEditor.getJSON());
     const title = page?.title ? `# ${page.title}\n\n` : "";
     clipboard.copy(`${title}${markdown}`);
     notifications.show({ message: t("Copied") });

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-alias-section.test.tsx

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

apps/server/src/common/helpers/prosemirror/html-embed-import-detect.spec.ts

@@ -1,4 +1,5 @@
-import { markdownToHtml, encodeHtmlEmbedSource } from '@docmost/editor-ext';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import { encodeHtmlEmbedSource } from '@docmost/editor-ext';
 import { htmlToJson } from '../../../collaboration/collaboration.util';
 import { hasHtmlEmbedNode, stripHtmlEmbedNodes } from './html-embed.util';
 
@@ -10,13 +11,12 @@ import { hasHtmlEmbedNode, stripHtmlEmbedNodes } from './html-embed.util';
  *
  * The block renders inside a sandboxed iframe, so this is not an XSS surface;
  * this exercises the REAL server import conversion path that ImportService uses
- * (`markdownToHtml` then `htmlToJson`; `processHTML` adds only a cheerio
- * link/iframe normalize pass which does not touch htmlEmbed divs) and asserts
- * that such a node is DETECTED and STRIPPABLE — so the share read path's
+ * (`markdownToProseMirror`, the canonical converter — issue #345/#347) and
+ * asserts that such a node is DETECTED and STRIPPABLE — so the share read path's
  * master-toggle strip can remove it when the workspace toggle is OFF.
  */
 describe('htmlEmbed smuggled via the raw serialized div in imported markdown/HTML', () => {
-  it('round-trips through markdownToHtml -> htmlToJson and is DETECTED (base64 data-source)', async () => {
+  it('round-trips through markdownToProseMirror and is DETECTED (base64 data-source)', async () => {
     const source = '<script>steal()</script>';
     const encoded = encodeHtmlEmbedSource(source);
     const md = [
@@ -27,12 +27,9 @@ describe('htmlEmbed smuggled via the raw serialized div in imported markdown/HTM
       'World',
     ].join('\n');
 
-    const html = await markdownToHtml(md);
-    // marked preserves the raw block-level div verbatim.
-    expect(html).toContain('data-type="htmlEmbed"');
-
-    const json = htmlToJson(html);
-    // The div parses into a real htmlEmbed node carrying the decoded source.
+    // The canonical importer parses the raw block-level div into a real
+    // htmlEmbed node carrying the decoded source.
+    const json = await markdownToProseMirror(md);
     expect(hasHtmlEmbedNode(json)).toBe(true);
 
     // Because it is detected, the share master-toggle strip can remove it.
@@ -59,8 +56,7 @@ describe('htmlEmbed smuggled via the raw serialized div in imported markdown/HTM
     // therefore stripping) does not depend on the source being well-formed, so
     // the bypass cannot be hidden by sending a malformed data-source.
     const md = `<div data-type="htmlEmbed" data-source="&lt;script&gt;x&lt;/script&gt;"></div>`;
-    const html = await markdownToHtml(md);
-    const json = htmlToJson(html);
+    const json = await markdownToProseMirror(md);
     expect(hasHtmlEmbedNode(json)).toBe(true);
     expect(hasHtmlEmbedNode(stripHtmlEmbedNodes(json))).toBe(false);
   });

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

@@ -43,6 +43,9 @@ function makeRepo(overrides: Record<string, jest.Mock> = {}) {
       workspaceId: v.workspaceId,
     })),
     update: jest.fn(async () => ({ id: 'run-1' })),
+    // #487: terminal finalize now goes through the CONDITIONAL write. Default
+    // returns a truthy row (the run WAS active -> this call wrote it).
+    finalizeIfActive: jest.fn(async () => ({ id: 'run-1', status: 'succeeded' })),
     markStopRequested: jest.fn(async () => ({ id: 'run-1' })),
     findActiveByChat: jest.fn(async () => undefined),
     findLatestByChat: jest.fn(async () => undefined),
@@ -336,14 +339,12 @@ describe('AiChatRunService run lifecycle', () => {
     await svc.finalizeRun('run-1', 'ws-1', 'error', 'provider blew up');
 
     expect(svc.isLocallyActive('run-1')).toBe(false);
-    expect(repo.update).toHaveBeenCalledWith(
+    // #487: the terminal write is CONDITIONAL (finalizeIfActive); finishedAt is
+    // stamped inside the repo method, so the service passes just status + error.
+    expect(repo.finalizeIfActive).toHaveBeenCalledWith(
       'run-1',
       'ws-1',
-      expect.objectContaining({
-        status: 'failed',
-        error: 'provider blew up',
-        finishedAt: expect.any(Date),
-      }),
+      expect.objectContaining({ status: 'failed', error: 'provider blew up' }),
     );
   });
 
@@ -366,8 +367,8 @@ describe('AiChatRunService run lifecycle', () => {
     // A second settle (e.g. a streamText callback firing after the catch) no-ops.
     await svc.finalizeRun('run-1', 'ws-1', 'completed', undefined);
 
-    expect(repo.update).toHaveBeenCalledTimes(1);
-    expect(repo.update).toHaveBeenCalledWith(
+    expect(repo.finalizeIfActive).toHaveBeenCalledTimes(1);
+    expect(repo.finalizeIfActive).toHaveBeenCalledWith(
       'run-1',
       'ws-1',
       expect.objectContaining({ status: 'failed', error: 'first' }),
@@ -389,8 +390,8 @@ describe('AiChatRunService run lifecycle', () => {
     const updateGate = new Promise((res) => {
       resolveUpdate = res;
     });
-    const update = jest.fn(() => updateGate);
-    const repo = makeRepo({ update });
+    const finalizeIfActive = jest.fn(() => updateGate);
+    const repo = makeRepo({ finalizeIfActive });
     const svc = new AiChatRunService(repo as never, makeEnv() as never);
     await svc.beginRun({
       chatId: 'chat-1',
@@ -399,23 +400,23 @@ describe('AiChatRunService run lifecycle', () => {
     });
 
     // Fire both before the (pending) update resolves. The first synchronously
-    // claims the entry (active.delete) and awaits update; the second, started in
-    // the same macrotask, finds the entry already gone and returns at the claim
-    // WITHOUT ever calling update.
+    // claims the entry (active.delete) and awaits the write; the second, started
+    // in the same macrotask, finds the entry already gone and returns at the claim
+    // WITHOUT ever writing.
     const p1 = svc.finalizeRun('run-1', 'ws-1', 'completed');
     const p2 = svc.finalizeRun('run-1', 'ws-1', 'error', 'safety-net');
 
     // The decisive assertion: exactly one caller reached the terminal UPDATE.
-    expect(update).toHaveBeenCalledTimes(1);
+    expect(finalizeIfActive).toHaveBeenCalledTimes(1);
 
     // Let the single in-flight update land; both calls resolve cleanly.
-    resolveUpdate({ id: 'run-1' });
+    resolveUpdate({ id: 'run-1', status: 'succeeded' });
     await Promise.all([p1, p2]);
 
-    expect(update).toHaveBeenCalledTimes(1);
+    expect(finalizeIfActive).toHaveBeenCalledTimes(1);
     // The winner is the FIRST caller ('completed' -> 'succeeded'); the late
     // 'error' settle never wrote, so it could not clobber the real status.
-    expect(update).toHaveBeenCalledWith(
+    expect(finalizeIfActive).toHaveBeenCalledWith(
       'run-1',
       'ws-1',
       expect.objectContaining({ status: 'succeeded' }),
@@ -431,10 +432,10 @@ describe('AiChatRunService run lifecycle', () => {
     // 409s until a restart. The fix updates FIRST and retries.
     let calls = 0;
     const repo = makeRepo({
-      update: jest.fn(async () => {
+      finalizeIfActive: jest.fn(async () => {
         calls += 1;
         if (calls === 1) throw new Error('deadlock detected');
-        return { id: 'run-1' };
+        return { id: 'run-1', status: 'succeeded' };
       }),
     });
     jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
@@ -447,26 +448,29 @@ describe('AiChatRunService run lifecycle', () => {
 
     await svc.finalizeRun('run-1', 'ws-1', 'completed');
 
-    // The retry landed the terminal write: the entry is dropped (slot freed) and
-    // the row carries the real terminal status — NOT stranded at 'running'.
+    // The retry landed the terminal write: the entry is dropped (slot freed), no
+    // zombie left, and the row carries the real terminal status.
     expect(svc.isLocallyActive('run-1')).toBe(false);
-    expect(repo.update).toHaveBeenCalledTimes(2);
-    expect(repo.update).toHaveBeenLastCalledWith(
+    expect(svc.hasZombie('run-1')).toBe(false);
+    expect(repo.finalizeIfActive).toHaveBeenCalledTimes(2);
+    expect(repo.finalizeIfActive).toHaveBeenLastCalledWith(
       'run-1',
       'ws-1',
       expect.objectContaining({ status: 'succeeded' }),
     );
   });
 
-  it('F6: if the terminal write keeps failing, the entry is RETAINED and a LATER settle completes it (chat not permanently 409d)', async () => {
+  it('#487 give-up: if the terminal write keeps failing, finalizeRun leaves a ZOMBIE (does NOT restore the entry) and settleZombie re-drives it', async () => {
     // Worst case: the DB is down for the whole first finalize (all attempts fail).
-    // The run must NOT be silently lost — the entry stays so a subsequent settle
-    // (a streamText callback, requestStop -> onAbort, or a future sweep) can retry.
+    // #487 changes the give-up behaviour: the entry is NOT restored (a restored
+    // entry is indistinguishable from a live run). Instead a ZOMBIE record holds
+    // the intended terminal status, and a re-drive (settleZombie — called by the
+    // reconcile / supersede / opportunistic paths) applies it later.
     let healthy = false;
     const repo = makeRepo({
-      update: jest.fn(async () => {
+      finalizeIfActive: jest.fn(async () => {
         if (!healthy) throw new Error('pool exhausted');
-        return { id: 'run-1' };
+        return { id: 'run-1', status: 'succeeded' };
       }),
     });
     jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
@@ -480,35 +484,83 @@ describe('AiChatRunService run lifecycle', () => {
       userId: 'user-1',
     });
 
-    // First settle: every bounded attempt fails -> entry retained, NOT settled.
+    // First settle: every bounded attempt fails -> ZOMBIE, entry NOT restored.
     await svc.finalizeRun('run-1', 'ws-1', 'completed');
-    expect(svc.isLocallyActive('run-1')).toBe(true);
-    // F12: the give-up emits ONE explicit, greppable ERROR (run + chat context)
-    // so an operator can tell "gave up, run held in memory" from a per-attempt
-    // blip — distinct from the per-attempt warns.
+    expect(svc.isLocallyActive('run-1')).toBe(false); // NOT a live entry
+    expect(svc.hasZombie('run-1')).toBe(true);
+    expect(svc.zombieRunIds()).toContain('run-1');
+    // The give-up emits ONE explicit, greppable ERROR mentioning the zombie.
     const gaveUp = errorSpy.mock.calls.some(
       (c) =>
         /NON-TERMINAL/.test(String(c[0])) &&
+        /ZOMBIE/.test(String(c[0])) &&
         /run-1/.test(String(c[0])) &&
         /chat-1/.test(String(c[0])),
     );
     expect(gaveUp).toBe(true);
+    // The settle notifier resolved as terminalWriteFailed (a subscriber learns the
+    // slot still needs the intended status applied).
+    const outcome = await svc.peekSettled('run-1');
+    expect(outcome).toEqual({
+      status: 'succeeded',
+      error: null,
+      terminalWriteFailed: true,
+    });
 
-    // The DB recovers; a later settle now succeeds and frees the slot.
+    // The DB recovers; a re-drive settles the zombie via the conditional UPDATE.
     healthy = true;
-    await svc.finalizeRun('run-1', 'ws-1', 'completed');
-    expect(svc.isLocallyActive('run-1')).toBe(false);
-    expect(repo.update).toHaveBeenLastCalledWith(
+    const redriven = await svc.settleZombie('run-1');
+    expect(redriven).toBe(true);
+    expect(svc.hasZombie('run-1')).toBe(false);
+    expect(repo.finalizeIfActive).toHaveBeenLastCalledWith(
       'run-1',
       'ws-1',
       expect.objectContaining({ status: 'succeeded' }),
     );
 
-    // And it is now idempotent: a further settle no-ops (terminal row already
-    // written), so a double-settle can never clobber the real status.
-    const callsBefore = repo.update.mock.calls.length;
+    // A later finalizeRun is idempotent (row already terminal): it no-ops at the
+    // once-gate, never re-writing.
+    const callsBefore = repo.finalizeIfActive.mock.calls.length;
     await svc.finalizeRun('run-1', 'ws-1', 'error', 'late');
-    expect(repo.update).toHaveBeenCalledTimes(callsBefore);
+    expect(repo.finalizeIfActive).toHaveBeenCalledTimes(callsBefore);
+  });
+
+  it('#487 double-settle collapses to a benign no-op (conditional write; notifier resolves once)', async () => {
+    // A second concurrent settle is stopped at the synchronous active.delete
+    // claim, so the terminal write runs exactly once and the notifier resolves
+    // exactly once with the FIRST settler's outcome.
+    const repo = makeRepo();
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'u1' });
+
+    await svc.finalizeRun('run-1', 'ws-1', 'aborted');
+    await svc.finalizeRun('run-1', 'ws-1', 'error', 'late'); // no-op
+
+    expect(repo.finalizeIfActive).toHaveBeenCalledTimes(1);
+    const outcome = await svc.peekSettled('run-1');
+    // peekSettled after resolve+delete falls through (notifier dropped, no zombie)
+    // -> undefined; the FIRST settler already resolved any earlier subscriber.
+    expect(outcome).toBeUndefined();
+  });
+
+  it('#487 late settledPromise subscriber gets the resolved outcome', async () => {
+    const repo = makeRepo();
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({ chatId: 'chat-1', workspaceId: 'ws-1', userId: 'u1' });
+
+    // Subscribe BEFORE settle: hold the promise reference (as supersede does).
+    const early = svc.peekSettled('run-1');
+    expect(early).toBeDefined();
+
+    await svc.finalizeRun('run-1', 'ws-1', 'completed');
+
+    // The reference grabbed before settle resolves with the written outcome, even
+    // though the notifier was dropped from the map on resolve (bounded).
+    await expect(early).resolves.toEqual({
+      status: 'succeeded',
+      error: null,
+      terminalWriteFailed: false,
+    });
   });
 
   it('recordStep / linkAssistantMessage are best-effort: a repo failure is swallowed', async () => {
@@ -525,3 +577,197 @@ describe('AiChatRunService run lifecycle', () => {
     ).resolves.toBeUndefined();
   });
 });
+
+describe('#487 AiChatRunService.supersede (CAS)', () => {
+  const chat = 'chat-1';
+  const ws = 'ws-1';
+
+  it('degrade: no active run on the chat -> caller sends a normal turn', async () => {
+    const repo = makeRepo({
+      findById: jest.fn(async () => undefined),
+      findActiveByChat: jest.fn(async () => undefined),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    expect(await svc.supersede(chat, 'run-x', ws)).toEqual({ kind: 'degrade' });
+  });
+
+  it('invalid: the target run belongs to a DIFFERENT chat -> 400', async () => {
+    const repo = makeRepo({
+      findById: jest.fn(async () => ({
+        id: 'run-x',
+        chatId: 'other-chat',
+        workspaceId: ws,
+      })),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    expect(await svc.supersede(chat, 'run-x', ws)).toEqual({ kind: 'invalid' });
+  });
+
+  it('mismatch: a DIFFERENT run is active than the one targeted -> current runId', async () => {
+    const repo = makeRepo({
+      findById: jest.fn(async () => ({ id: 'run-x', chatId: chat, workspaceId: ws })),
+      findActiveByChat: jest.fn(async () => ({
+        id: 'run-live',
+        chatId: chat,
+        workspaceId: ws,
+        status: 'running',
+      })),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    expect(await svc.supersede(chat, 'run-x', ws)).toEqual({
+      kind: 'mismatch',
+      activeRunId: 'run-live',
+    });
+  });
+
+  it('ready: the target IS active -> stop it, await its (fast) settle, free the slot', async () => {
+    // Simulate a live long TOOL (NOT a slow UPDATE): the run stays active until an
+    // explicit Stop unwinds it; commit-1's race makes that settle land quickly.
+    // The abort listener stands in for streamText's onAbort -> finalizeRun.
+    const repo = makeRepo({
+      findById: jest.fn(async () => ({
+        id: 'run-1',
+        chatId: chat,
+        workspaceId: ws,
+        status: 'aborted',
+        error: null,
+      })),
+      findActiveByChat: jest.fn(async () => ({
+        id: 'run-1',
+        chatId: chat,
+        workspaceId: ws,
+        status: 'running',
+      })),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const handle = await svc.beginRun({ chatId: chat, workspaceId: ws, userId: 'u1' });
+    handle.signal.addEventListener('abort', () => {
+      void svc.finalizeRun('run-1', ws, 'aborted');
+    });
+
+    // supersede: getRun -> getActiveByChat(==target) -> requestStop -> the abort
+    // listener settles the run -> awaitSettled resolves -> ready.
+    expect(await svc.supersede(chat, 'run-1', ws, 10_000)).toEqual({
+      kind: 'ready',
+    });
+    expect(handle.signal.aborted).toBe(true); // Stop reached the run
+  });
+
+  it('timeout: the target never settles within W -> 409 SUPERSEDE_TIMEOUT (nothing persisted)', async () => {
+    const repo = makeRepo({
+      findById: jest.fn(async () => ({ id: 'run-1', chatId: chat, workspaceId: ws })),
+      findActiveByChat: jest.fn(async () => ({
+        id: 'run-1',
+        chatId: chat,
+        workspaceId: ws,
+        status: 'running',
+      })),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({ chatId: chat, workspaceId: ws, userId: 'u1' });
+    // Do NOT settle the run: a tiny W elapses -> timeout.
+    const result = await svc.supersede(chat, 'run-1', ws, 30);
+    expect(result).toEqual({ kind: 'timeout' });
+  });
+
+  it('ready then a DUPLICATE supersede POST degrades (the run is already gone)', async () => {
+    let active: unknown = {
+      id: 'run-1',
+      chatId: chat,
+      workspaceId: ws,
+      status: 'running',
+    };
+    const repo = makeRepo({
+      findById: jest.fn(async () => ({
+        id: 'run-1',
+        chatId: chat,
+        workspaceId: ws,
+        status: 'aborted',
+        error: null,
+      })),
+      findActiveByChat: jest.fn(async () => active),
+      finalizeIfActive: jest.fn(async () => {
+        active = undefined; // settling frees the active slot
+        return { id: 'run-1', status: 'aborted' };
+      }),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    const handle = await svc.beginRun({ chatId: chat, workspaceId: ws, userId: 'u1' });
+    handle.signal.addEventListener('abort', () => {
+      void svc.finalizeRun('run-1', ws, 'aborted');
+    });
+
+    expect(await svc.supersede(chat, 'run-1', ws, 10_000)).toEqual({
+      kind: 'ready',
+    });
+    // The duplicate POST for the same target now finds no active run -> degrade.
+    expect(await svc.supersede(chat, 'run-1', ws)).toEqual({ kind: 'degrade' });
+  });
+
+  it('reconcileStaleRuns: aborts a stale run with NO entry/zombie; NEVER touches a live entry', async () => {
+    const finalizeIfActive = jest.fn(async () => ({ id: 'x', status: 'aborted' }));
+    const repo = makeRepo({
+      insert: jest.fn(async (v: any) => ({
+        id: 'live-1',
+        status: 'running',
+        chatId: v.chatId,
+        workspaceId: v.workspaceId,
+      })),
+      finalizeIfActive,
+      findStaleActive: jest.fn(async () => [
+        { id: 'orphan-1', workspaceId: ws, chatId: 'c-orphan' },
+        { id: 'live-1', workspaceId: ws, chatId: 'c-live' },
+      ]),
+    });
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    // A LIVE run this replica owns (in the `active` map).
+    await svc.beginRun({ chatId: 'c-live', workspaceId: ws, userId: 'u1' });
+    expect(svc.isLocallyActive('live-1')).toBe(true);
+
+    const aborted = await svc.reconcileStaleRuns(15 * 60 * 1000);
+    expect(aborted).toBe(1);
+    // The orphan (no entry) was aborted; the live entry was NEVER passed to the DB.
+    expect(finalizeIfActive).toHaveBeenCalledTimes(1);
+    expect(finalizeIfActive).toHaveBeenCalledWith(
+      'orphan-1',
+      ws,
+      expect.objectContaining({ status: 'aborted' }),
+    );
+    expect(svc.isLocallyActive('live-1')).toBe(true);
+  });
+
+  it('gave-up zombie: supersede applies the intended status (settleZombie) then is ready', async () => {
+    let healthy = false;
+    let active: unknown = {
+      id: 'run-1',
+      chatId: chat,
+      workspaceId: ws,
+      status: 'running',
+    };
+    const repo = makeRepo({
+      findById: jest.fn(async () => ({ id: 'run-1', chatId: chat, workspaceId: ws })),
+      findActiveByChat: jest.fn(async () => active),
+      finalizeIfActive: jest.fn(async () => {
+        if (!healthy) throw new Error('db down');
+        active = undefined;
+        return { id: 'run-1', status: 'aborted' };
+      }),
+    });
+    jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+    jest.spyOn(Logger.prototype, 'error').mockImplementation(() => undefined);
+    const svc = new AiChatRunService(repo as never, makeEnv() as never);
+    await svc.beginRun({ chatId: chat, workspaceId: ws, userId: 'u1' });
+
+    // The run's terminal write gives up -> zombie (row still 'running').
+    await svc.finalizeRun('run-1', ws, 'aborted');
+    expect(svc.hasZombie('run-1')).toBe(true);
+
+    // The DB recovers; supersede awaits the (already-resolved, terminalWriteFailed)
+    // settle, then settleZombie applies the intended status -> ready.
+    healthy = true;
+    expect(await svc.supersede(chat, 'run-1', ws, 10_000)).toEqual({
+      kind: 'ready',
+    });
+    expect(svc.hasZombie('run-1')).toBe(false);
+  });
+});

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

@@ -34,6 +34,88 @@ export class RunAlreadyActiveError extends Error {
 export type TurnTerminalStatus = 'completed' | 'error' | 'aborted';
 export type RunTerminalStatus = 'succeeded' | 'failed' | 'aborted';
 
+/** The terminal run statuses — the row is done once it reads one of these. */
+export const RUN_TERMINAL_STATUSES: readonly RunTerminalStatus[] = [
+  'succeeded',
+  'failed',
+  'aborted',
+];
+
+/** Whether a persisted run status is terminal (settled). */
+export function isRunTerminal(status: string | null | undefined): boolean {
+  return (
+    status === 'succeeded' || status === 'failed' || status === 'aborted'
+  );
+}
+
+/**
+ * #487: the outcome a run's {@link AiChatRunService.finalizeRun} settled with.
+ * `terminalWriteFailed` = the terminal write GAVE UP after the bounded retry, so
+ * the row is still non-terminal ('running') and a ZOMBIE record holds the
+ * `intended` status for a later re-drive (reconcile / supersede / boot sweep). A
+ * subscriber (supersede, #487 commit 3) uses this to decide whether the slot is
+ * genuinely free or must first have the intended status applied.
+ */
+export interface RunSettleOutcome {
+  status: RunTerminalStatus;
+  error: string | null;
+  terminalWriteFailed: boolean;
+}
+
+/**
+ * #487: how long a supersede waits for the target run to settle after Stop before
+ * it degrades to `SUPERSEDE_TIMEOUT`. W=10s is generous under a HEALTHY DB: commit
+ * 1's race-on-abort makes an in-app tool abort->settle in ms/hundreds of ms, so a
+ * live run releases its slot well within the window. Under a DB brownout the
+ * timeout is normal (the write cannot land); W must NOT be raised to paper
+ * over a slow DB — a SUPERSEDE_TIMEOUT is the honest signal (nothing persisted,
+ * the composer keeps the user's text). Env-tunable for ops, default 10s.
+ */
+export const SUPERSEDE_SETTLE_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.AI_CHAT_SUPERSEDE_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 10_000;
+})();
+
+/**
+ * #487: the result of the supersede CAS ({@link AiChatRunService.supersede}).
+ *  - `degrade`  : no active run on the chat (it ended between click and POST) —
+ *                 the caller sends a NORMAL turn (NOT a mismatch);
+ *  - `invalid`  : the target runId belongs to a DIFFERENT chat (malformed CAS 400);
+ *  - `mismatch` : a DIFFERENT run is active than the one the client targeted —
+ *                 409 SUPERSEDE_TARGET_MISMATCH carrying the current `activeRunId`
+ *                 (the client does NOT auto-retry);
+ *  - `timeout`  : the target did not settle within W — 409 SUPERSEDE_TIMEOUT,
+ *                 nothing persisted;
+ *  - `ready`    : the target was stopped AND settled (or its zombie's intended was
+ *                 applied) — the slot is free; the caller may beginRun the new run.
+ */
+export type SupersedeResult =
+  | { kind: 'degrade' }
+  | { kind: 'invalid' }
+  | { kind: 'mismatch'; activeRunId: string }
+  | { kind: 'timeout' }
+  | { kind: 'ready' };
+
+/** A one-shot settle notifier (#487): `resolve` is called EXACTLY ONCE. */
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+}
+
+/**
+ * #487: a run whose terminal write GAVE UP (every bounded attempt failed). The
+ * row is stranded non-terminal ('running'); this record is the ONLY thing that
+ * distinguishes it from a live run, and carries the `intended` terminal status so
+ * a re-drive can apply it via the conditional UPDATE. Process-local (phase-1
+ * single-process assumption): a restart drops it, and the boot sweep then writes
+ * 'aborted' over the intended — a documented loss (see finalizeRun).
+ */
+interface ZombieRun {
+  workspaceId: string;
+  chatId: string;
+  intended: { status: RunTerminalStatus; error: string | null };
+}
+
 export function mapTurnStatusToRun(
   status: TurnTerminalStatus,
 ): RunTerminalStatus {
@@ -101,6 +183,22 @@ export class AiChatRunService implements OnModuleInit {
   // uptime — negligible in phase 1's single process.
   private readonly settled = new Set<string>();
 
+  // #487 runId -> one-shot settle notifier. Kept in a SEPARATE map from `active`
+  // ON PURPOSE: it must OUTLIVE the `active.delete` claim inside finalizeRun (the
+  // claim frees the slot the instant finalize starts), so a subscriber can still
+  // await the outcome after the entry is gone. Created in beginRun, resolved
+  // EXACTLY ONCE in finalizeRun, then removed (bounded). Absence => this replica
+  // has no live notifier: a subscriber falls back to the zombie map, then to the
+  // row (see peekSettled). Process-local (phase-1 single-process assumption).
+  private readonly settledPromises = new Map<string, Deferred<RunSettleOutcome>>();
+
+  // #487 runId -> ZOMBIE record: a run whose terminal write gave up (row stranded
+  // non-terminal). BOUNDED — an entry is added only on give-up and removed on a
+  // successful re-drive (settleZombie) or when the row is found already terminal;
+  // a process restart clears it (and the boot sweep settles the stranded row).
+  // Process-local (phase-1 single-process assumption).
+  private readonly zombies = new Map<string, ZombieRun>();
+
   // Bounded retry for the terminal write (F6): a single PK UPDATE can fail
   // transiently under many fire-and-forget writes (pool exhaustion, deadlock, a
   // brief connection blip). Riding out that blip in-place matters because the
@@ -224,6 +322,10 @@ export class AiChatRunService implements OnModuleInit {
       chatId: args.chatId,
       workspaceId: args.workspaceId,
     });
+    // #487: arm the one-shot settle notifier BEFORE returning, so a subscriber
+    // that races in immediately after begin always finds a promise to await. It
+    // is resolved exactly once when the run settles (or gives up).
+    this.settledPromises.set(run.id, this.makeDeferred<RunSettleOutcome>());
     return { runId: run.id, signal: controller.signal };
   }
 
@@ -263,47 +365,43 @@ export class AiChatRunService implements OnModuleInit {
   }
 
   /**
-   * Finalize a run to its terminal status (succeeded / failed / aborted),
-   * stamping finishedAt + any error. Best-effort, but ROBUST against a transient
-   * terminal-write failure (F6) AND atomically safe against a concurrent settle.
+   * Finalize a run to its terminal status (succeeded / failed / aborted) via a
+   * CONDITIONAL UPDATE, stamping finishedAt + any error. Atomically safe against a
+   * concurrent settle AND robust against a transient terminal-write failure.
    *
    * ATOMIC ONCE-CLAIM (the gate must close in ONE synchronous tick): two
    * finalizeRun calls for the SAME run can race — the documented real path is
    * AiChatService.stream's safety-net catch settling the turn to 'error' while a
    * streamText terminal callback (onFinish/onAbort/onError) ALSO settles it. The
-   * `settled.has` check alone is NOT a gate: it is read BEFORE the awaited UPDATE,
-   * so two callers can both see `false` and both write the row (last-write-wins
-   * clobbers the real terminal status, and the bounded retry only widens that
-   * window). The claim therefore happens via `active.delete`, a SYNCHRONOUS
-   * check-and-clear with NO await between the gate and the entry removal: the
-   * second concurrent caller finds the entry already gone and returns in the same
-   * tick, before any UPDATE. The transition "nobody is finalizing" -> "I am
-   * finalizing" is thus a single atomic step.
+   * claim happens via `active.delete`, a SYNCHRONOUS check-and-clear with NO await
+   * between the gate and the entry removal: the second concurrent caller finds the
+   * entry already gone and returns in the same tick, before any UPDATE.
    *
-   * ORDER MATTERS (F6): once we own the claim, the terminal UPDATE happens FIRST;
-   * only once it SUCCEEDS do we record the run as settled. If the UPDATE fails on
-   * every bounded attempt we RESTORE the in-memory entry, leave the run UNsettled,
-   * and emit an ERROR signal that the row is left non-terminal 'running' (which
-   * would 409 every future turn in the chat until recovery). An in-process retry
-   * by a LATER settle is only POSSIBLE, never guaranteed: it needs (a) the entry
-   * to have been restored at the give-up path AND (b) a fresh settler to arrive
-   * AFTER that restore. A concurrent settler that arrives DURING the retry window
-   * — while the entry is deleted for backoff and not yet restored — is consumed at
-   * the synchronous `active.delete` claim (it finds nothing to delete and returns
-   * a no-op), so it does NOT become an in-process retrier. The NO-streamText path
-   * (the turn threw before streamText was wired, so ONLY the safety-net ever
-   * settles) likewise has no second in-process settler at all. The UNCONDITIONAL
-   * backstop in every case is the boot sweep on the next restart (phase 1 has no
-   * periodic in-process sweep); the retained entry is bounded (cleared on restart)
-   * and harmless meanwhile.
+   * ALL TERMINAL WRITES ARE CONDITIONAL (#487): `finalizeIfActive` only flips a
+   * row still in pending|running (mirror of the assistant message's
+   * `onlyIfStreaming`). So even a settle that DID reach the UPDATE (e.g. a
+   * reconcile stamp racing an owner finalize) can never clobber a terminal status
+   * — the loser matches nothing and is a benign no-op. `active.delete` is the
+   * fast, in-process gate; the conditional WHERE is the authoritative one.
    *
-   * IDEMPOTENT on SUCCESS (#184 review): the terminal write happens AT MOST ONCE
-   * per run. After a successful write the once-gate keys off {@link settled} (the
-   * terminal row already written) so a settle arriving AFTER the entry was already
-   * dropped-and-settled returns early; a settle racing the in-flight write is
-   * stopped earlier still, by the `active.delete` claim. Either way a genuine
-   * double-settle collapses to a single write and a late settle can never clobber
-   * the real terminal status or double-write the row.
+   * ZOMBIE ON GIVE-UP (#487): if every bounded attempt THROWS (the DB is down for
+   * the whole finalize), we do NOT restore the entry. The row is stranded
+   * non-terminal ('running'); we record a ZOMBIE `{ terminalWriteFailed, intended
+   * }` (the ONLY thing distinguishing this dead run from a live one) and resolve
+   * the settle notifier with `terminalWriteFailed: true`. A restore would make the
+   * zombie indistinguishable from a live run to every reader; instead a re-drive
+   * (settleZombie, called by the periodic reconcile / supersede / opportunistic
+   * paths) applies the intended status later via the same conditional UPDATE.
+   *
+   * DOCUMENTED LOSS (#487, single-process phase 1): if the process RESTARTS before
+   * a zombie is re-driven, the in-memory zombie map is gone and the boot sweep
+   * (unconditional) writes 'aborted' over the ACTUAL intended status. This is
+   * unavoidable while the run lifecycle is single-process — there is no durable
+   * record of `intended`; a cross-process durable intent is deferred to phase 2.
+   *
+   * IDEMPOTENT: the settle notifier resolves EXACTLY ONCE; a second settle is
+   * stopped at `settled.has` or the `active.delete` claim, so a double-settle
+   * collapses to a single write and can never double-resolve or clobber the row.
    */
   async finalizeRun(
     runId: string,
@@ -314,13 +412,17 @@ export class AiChatRunService implements OnModuleInit {
     // ---- Atomic once-claim (synchronous; NO await before the gate closes) ----
     // Already terminally written -> idempotent no-op.
     if (this.settled.has(runId)) return;
-    // Capture the entry BEFORE the delete so a total-failure path can restore it.
+    // Capture the entry BEFORE the delete for the give-up log context.
     const entry = this.active.get(runId);
     // SYNCHRONOUS check-and-clear: the FIRST caller deletes (claims) the entry;
     // any concurrent SECOND caller finds nothing to delete and returns HERE, in
     // the same tick, before any await — so it can never reach the UPDATE.
     if (!this.active.delete(runId)) return;
 
+    const status = mapTurnStatusToRun(turnStatus);
+    const err = error ?? null;
+    const chatId = entry?.chatId ?? 'unknown';
+
     let lastError: unknown;
     for (
       let attempt = 1;
@@ -328,47 +430,294 @@ export class AiChatRunService implements OnModuleInit {
       attempt++
     ) {
       try {
-        await this.runRepo.update(runId, workspaceId, {
-          status: mapTurnStatusToRun(turnStatus),
-          finishedAt: new Date(),
-          error: error ?? null,
+        const row = await this.runRepo.finalizeIfActive(runId, workspaceId, {
+          status,
+          error: err,
         });
-        // Terminal write landed: arm the once-gate. The entry is already gone
-        // (claimed above); we do NOT restore it. The slot is now free.
+        // No throw => the row is now terminal (we wrote it, or it was ALREADY
+        // terminal — another writer won the conditional UPDATE, a benign no-op).
         this.settled.add(runId);
+        this.zombies.delete(runId);
+        // Resolve with the persisted outcome: our status when WE wrote it, else
+        // the row's real terminal status (re-read on the already-terminal path so
+        // a subscriber never sees a status we did not actually persist).
+        const outcome: RunSettleOutcome = row
+          ? { status, error: err, terminalWriteFailed: false }
+          : await this.readTerminalOutcome(runId, workspaceId, status, err);
+        this.resolveSettled(runId, outcome);
         return;
-      } catch (err) {
-        lastError = err;
+      } catch (err2) {
+        lastError = err2;
         this.logger.warn(
           `Failed to finalize run ${runId} (attempt ${attempt}/${
             AiChatRunService.FINALIZE_MAX_ATTEMPTS
-          }): ${err instanceof Error ? err.message : 'unknown error'}`,
+          }): ${err2 instanceof Error ? err2.message : 'unknown error'}`,
         );
         if (attempt < AiChatRunService.FINALIZE_MAX_ATTEMPTS) {
           await this.delay(AiChatRunService.FINALIZE_RETRY_BASE_MS * attempt);
         }
       }
     }
-    // Every attempt failed: this is a give-up, materially worse than a per-attempt
-    // blip — the row is left NON-TERMINAL ('running'), so emit ONE explicit,
-    // greppable ERROR so an operator can tell "survived a blip" from "gave up, run
-    // held in memory until recovery" (the last warn alone says only "attempt 3/3").
+    // Every attempt threw: GIVE UP. The row is stranded non-terminal ('running').
+    // Do NOT restore the entry (a restored entry is indistinguishable from a live
+    // run); leave a ZOMBIE record instead, and resolve the notifier as
+    // terminalWriteFailed so a subscriber knows the slot still needs the intended
+    // status applied. One explicit, greppable ERROR so an operator can tell a
+    // give-up from a per-attempt blip.
     this.logger.error(
-      `Run ${runId} (chat ${entry?.chatId ?? 'unknown'}) left NON-TERMINAL ` +
-        `('running'): terminal write failed after ${
-          AiChatRunService.FINALIZE_MAX_ATTEMPTS
-        } attempts; entry retained in memory, recovery deferred to next settle / ` +
-        `boot sweep`,
+      `Run ${runId} (chat ${chatId}) left NON-TERMINAL ('running'): terminal ` +
+        `write failed after ${AiChatRunService.FINALIZE_MAX_ATTEMPTS} attempts; ` +
+        `ZOMBIE recorded (intended '${status}'), recovery deferred to reconcile / ` +
+        `supersede / boot sweep`,
       lastError,
     );
-    // RESTORE the claimed entry (and leave the run UNsettled) so a LATER settle
-    // that arrives AFTER this restore MAY retry the terminal write — but that
-    // in-process retry is NOT guaranteed (a concurrent settler caught in the retry
-    // window above is consumed at the `active.delete` claim, and the no-streamText
-    // path has no second settler at all). The UNCONDITIONAL backstop in every case
-    // is the boot sweep on the next restart; the restored entry is bounded and
-    // cleared on restart.
-    if (entry) this.active.set(runId, entry);
+    this.zombies.set(runId, {
+      workspaceId,
+      chatId,
+      intended: { status, error: err },
+    });
+    this.resolveSettled(runId, { status, error: err, terminalWriteFailed: true });
+  }
+
+  /**
+   * #487: re-drive a zombie run's intended terminal write (the conditional
+   * UPDATE). Called by the periodic reconcile (commit 4), an opportunistic
+   * single-chat reconcile, and supersede (commit 3). On success — the row is now
+   * terminal (written OR found already terminal) — the zombie is cleared and the
+   * once-gate armed; on another failure the zombie is kept for a later retry.
+   * Returns true when the row is now terminal. Best-effort; never throws.
+   */
+  async settleZombie(runId: string): Promise<boolean> {
+    const z = this.zombies.get(runId);
+    if (!z) return false;
+    try {
+      await this.runRepo.finalizeIfActive(runId, z.workspaceId, {
+        status: z.intended.status,
+        error: z.intended.error,
+      });
+      this.zombies.delete(runId);
+      this.settled.add(runId);
+      return true;
+    } catch (err) {
+      this.logger.warn(
+        `Re-drive of zombie run ${runId} (chat ${z.chatId}) failed; will retry ` +
+          `later: ${err instanceof Error ? err.message : 'unknown error'}`,
+      );
+      return false;
+    }
+  }
+
+  /**
+   * #487 reconcile clause (c): abort runs the DB still shows active (pending|
+   * running) but that this replica does NOT own — NO live entry AND NO zombie —
+   * and that have been UNTOUCHED past `staleMs` (from last-progress `updated_at`,
+   * NOT startedAt, so a legit long marathon is never a candidate). "No entry" is
+   * the PRIMARY gate: a live entry (an actively-executing run on this replica) is
+   * NEVER aborted, whatever its age. Returns the number aborted. Best-effort —
+   * never throws (a periodic-job failure must not crash the process).
+   */
+  async reconcileStaleRuns(staleMs: number): Promise<number> {
+    let candidates: Array<{ id: string; workspaceId: string; chatId: string }>;
+    try {
+      candidates = await this.runRepo.findStaleActive(staleMs);
+    } catch (err) {
+      this.logger.warn(
+        `Reconcile (stale runs) query failed: ${
+          err instanceof Error ? err.message : 'unknown error'
+        }`,
+      );
+      return 0;
+    }
+    let aborted = 0;
+    for (const c of candidates) {
+      // PRIMARY gate: never touch a live entry, and never race a zombie we are
+      // already re-driving (settleZombie owns those).
+      if (this.active.has(c.id) || this.zombies.has(c.id)) continue;
+      try {
+        const row = await this.runRepo.finalizeIfActive(c.id, c.workspaceId, {
+          status: 'aborted',
+          error: 'Run aborted by reconcile: no live runner (stale).',
+        });
+        if (row) {
+          aborted += 1;
+          this.settled.add(c.id);
+        }
+      } catch (err) {
+        this.logger.warn(
+          `Reconcile abort of stale run ${c.id} failed: ${
+            err instanceof Error ? err.message : 'unknown error'
+          }`,
+        );
+      }
+    }
+    return aborted;
+  }
+
+  /**
+   * #487: the run's settle outcome as seen by THIS replica, or undefined when it
+   * has no record (the caller then reads the row — the DB is the source of truth).
+   * A LIVE deferred (still settling, or resolved-but-not-yet-consumed) wins; a
+   * ZOMBIE synthesizes the give-up outcome. A subscriber (supersede) races this
+   * against a timeout.
+   */
+  peekSettled(runId: string): Promise<RunSettleOutcome> | undefined {
+    const d = this.settledPromises.get(runId);
+    if (d) return d.promise;
+    const z = this.zombies.get(runId);
+    if (z) {
+      return Promise.resolve({
+        status: z.intended.status,
+        error: z.intended.error,
+        terminalWriteFailed: true,
+      });
+    }
+    return undefined;
+  }
+
+  /**
+   * #487: await a run's settle outcome, bounded by `timeoutMs`. Returns the
+   * outcome on settle, or undefined on TIMEOUT (or when this replica has no record
+   * of the run and its row is not terminal). Uses the LIVE settle notifier / the
+   * zombie synth when present; else reads the row (the DB is the source of truth
+   * once the in-memory record is gone). The subscriber (supersede) grabs this
+   * right after Stop; commit 1's race makes the settle land in ms on a healthy DB.
+   */
+  async awaitSettled(
+    runId: string,
+    workspaceId: string,
+    timeoutMs: number,
+  ): Promise<RunSettleOutcome | undefined> {
+    const pending = this.peekSettled(runId);
+    if (pending) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<undefined>((resolve) => {
+        timer = setTimeout(() => resolve(undefined), timeoutMs);
+        timer.unref?.();
+      });
+      try {
+        return await Promise.race([pending, timeout]);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    }
+    // No live notifier and no zombie: read the row (already settled-and-written,
+    // or unknown here). A terminal row is an outcome; anything else -> undefined.
+    const row = await this.runRepo.findById(runId, workspaceId);
+    if (row && isRunTerminal(row.status)) {
+      return {
+        status: row.status as RunTerminalStatus,
+        error: row.error ?? null,
+        terminalWriteFailed: false,
+      };
+    }
+    return undefined;
+  }
+
+  /**
+   * #487: the SERVER supersede CAS for `POST /stream { supersede: { runId: X } }`.
+   * Atomically transitions "X is the chat's active run" -> "X is stopped, settled,
+   * slot free" so the caller can start a replacement run. See {@link
+   * SupersedeResult} for the branch semantics.
+   *
+   * On a `ready` result the caller MUST still go through the normal beginRun gate
+   * (the partial unique index) — between the slot freeing here and beginRun a
+   * neighbouring tab's ordinary POST can win the slot (documented SLOT-THEFT: the
+   * loser then gets a MISMATCH carrying the NEW runId). There is also NO side-
+   * effect quiescence: an in-flight write of the stopped run may still land AFTER
+   * the new run starts (commit 1 stops the NEXT call, not one already committing),
+   * so the caller adds a prompt note to the new run.
+   */
+  async supersede(
+    chatId: string,
+    targetRunId: string,
+    workspaceId: string,
+    timeoutMs: number = SUPERSEDE_SETTLE_TIMEOUT_MS,
+  ): Promise<SupersedeResult> {
+    // Validate the target belongs to THIS chat (a CAS targeting another chat's run
+    // is malformed -> 400). A missing row is NOT invalid: the run may have ended
+    // and been pruned; the active-run check below decides degrade vs mismatch.
+    const target = await this.getRun(targetRunId, workspaceId);
+    if (target && target.chatId !== chatId) return { kind: 'invalid' };
+
+    const active = await this.getActiveForChat(chatId, workspaceId);
+    // No active run: it ended between the client's click and this POST — this is a
+    // DEGRADE to a normal send, NOT a mismatch (the user's intent still holds).
+    if (!active) return { kind: 'degrade' };
+    // A DIFFERENT run is active than the one the client saw -> mismatch. The
+    // client does not auto-retry; it surfaces the new runId.
+    if (active.id !== targetRunId) {
+      return { kind: 'mismatch', activeRunId: active.id };
+    }
+
+    // The target IS active: stop it, then await its settle within W.
+    await this.requestStop(targetRunId, workspaceId);
+    const outcome = await this.awaitSettled(targetRunId, workspaceId, timeoutMs);
+    if (!outcome) return { kind: 'timeout' };
+    // Gave up (terminal write failed): apply the intended status via the
+    // conditional UPDATE so the slot actually frees. If that ALSO fails, the row
+    // is still stranded -> treat as a timeout (nothing persisted for the new run).
+    if (outcome.terminalWriteFailed) {
+      const settled = await this.settleZombie(targetRunId);
+      if (!settled) return { kind: 'timeout' };
+    }
+    return { kind: 'ready' };
+  }
+
+  /** #487 test/diagnostic seam: whether a give-up zombie is held for this run. */
+  hasZombie(runId: string): boolean {
+    return this.zombies.has(runId);
+  }
+
+  /** #487: every zombie runId held on this replica (reconcile clause a, commit 4). */
+  zombieRunIds(): string[] {
+    return [...this.zombies.keys()];
+  }
+
+  /** #487: create a one-shot deferred (resolve captured for a later single call). */
+  private makeDeferred<T>(): Deferred<T> {
+    let resolve!: (value: T) => void;
+    const promise = new Promise<T>((r) => {
+      resolve = r;
+    });
+    return { promise, resolve };
+  }
+
+  /** #487: resolve a run's settle notifier EXACTLY ONCE, then drop it (bounded).
+   *  A subscriber that already grabbed the promise still resolves; a later one
+   *  falls back to the zombie map / the row (see peekSettled). */
+  private resolveSettled(runId: string, outcome: RunSettleOutcome): void {
+    const d = this.settledPromises.get(runId);
+    if (!d) return;
+    this.settledPromises.delete(runId);
+    d.resolve(outcome);
+  }
+
+  /** #487: read the persisted terminal outcome when the conditional finalize was a
+   *  no-op (the row was already terminal). Falls back to the intended status when
+   *  the read fails or the row is unexpectedly missing/non-terminal. */
+  private async readTerminalOutcome(
+    runId: string,
+    workspaceId: string,
+    fallbackStatus: RunTerminalStatus,
+    fallbackError: string | null,
+  ): Promise<RunSettleOutcome> {
+    try {
+      const row = await this.runRepo.findById(runId, workspaceId);
+      if (row && isRunTerminal(row.status)) {
+        return {
+          status: row.status as RunTerminalStatus,
+          error: row.error ?? null,
+          terminalWriteFailed: false,
+        };
+      }
+    } catch {
+      // Fall through to the intended status — best-effort only.
+    }
+    return {
+      status: fallbackStatus,
+      error: fallbackError,
+      terminalWriteFailed: false,
+    };
   }
 
   /** Small async backoff between terminal-write retries (F6). Isolated so it is

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.controller.export.spec.ts

@@ -115,7 +115,7 @@ describe('finalizeAssistant dispatch (planFinalizeAssistant + applyFinalize)', (
 
   // Drive the SAME applyFinalize the service calls (no duplicated logic).
   async function dispatchFinalize(
-    repo: { insert: jest.Mock; update: jest.Mock },
+    repo: { insert: jest.Mock; finalizeOwner: jest.Mock },
     assistantId: string | undefined,
     flushed: AssistantFlush,
   ): Promise<void> {
@@ -135,21 +135,22 @@ describe('finalizeAssistant dispatch (planFinalizeAssistant + applyFinalize)', (
     expect(planFinalizeAssistant(undefined)).toEqual({ kind: 'insert' });
   });
 
-  it('(a) upfront insert succeeded -> finalize UPDATEs the row by id', async () => {
-    const repo = { insert: jest.fn(), update: jest.fn() };
+  it('(a) upfront insert succeeded -> finalize CONDITIONALLY updates the row by id (#487 owner-write)', async () => {
+    const repo = { insert: jest.fn(), finalizeOwner: jest.fn() };
     const flushed = flushAssistant([], 'final answer', 'completed', {
       finishReason: 'stop',
     });
     await dispatchFinalize(repo, 'a1', flushed);
-    expect(repo.update).toHaveBeenCalledWith('a1', workspaceId, flushed);
+    // #487: the owner write is the CONDITIONAL finalizeOwner, not a raw update.
+    expect(repo.finalizeOwner).toHaveBeenCalledWith('a1', workspaceId, flushed);
     expect(repo.insert).not.toHaveBeenCalled();
   });
 
   it('(b) upfront insert failed -> finalize INSERTs the terminal payload', async () => {
-    const repo = { insert: jest.fn(), update: jest.fn() };
+    const repo = { insert: jest.fn(), finalizeOwner: jest.fn() };
     const flushed = flushAssistant([], 'partial', 'error', { error: 'boom' });
     await dispatchFinalize(repo, undefined, flushed);
-    expect(repo.update).not.toHaveBeenCalled();
+    expect(repo.finalizeOwner).not.toHaveBeenCalled();
     expect(repo.insert).toHaveBeenCalledTimes(1);
     const arg = repo.insert.mock.calls[0][0];
     // The fallback insert carries the terminal content/status/metadata.

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

@@ -0,0 +1,279 @@
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  HttpException,
+} from '@nestjs/common';
+import { AiChatController } from './ai-chat.controller';
+import type { User, Workspace } from '@docmost/db/types/entity.types';
+
+/**
+ * #487 commit 3 — the single concurrency GATE (both modes) + the server supersede
+ * CAS, at the controller boundary. The gate + CAS run BEFORE res.hijack(), so a
+ * rejected concurrent start / a CAS branch returns clean JSON (an HttpException
+ * the controller's post-hijack catch re-serializes). These assert the OBSERVABLE
+ * HTTP contract against the real controller + a stubbed run service.
+ */
+describe('#487 AiChatController.stream — gate + supersede', () => {
+  const user = { id: 'u1' } as User;
+
+  function wsWith(autonomousRuns: boolean): Workspace {
+    return {
+      id: 'ws1',
+      settings: { ai: { chat: true, autonomousRuns } },
+    } as unknown as Workspace;
+  }
+
+  function makeReqRes(body: Record<string, unknown>) {
+    const req = {
+      raw: { sessionId: 'sess', once: jest.fn(), destroyed: false },
+      body,
+    };
+    const res = {
+      raw: {
+        writableEnded: false,
+        headersSent: false,
+        on: jest.fn(),
+        once: jest.fn(),
+        setHeader: jest.fn(),
+        end: jest.fn(),
+        statusCode: 200,
+        flushHeaders: jest.fn(),
+      },
+      hijack: jest.fn(),
+      status: jest.fn().mockReturnThis(),
+      send: jest.fn(),
+    };
+    return { req, res };
+  }
+
+  function makeController(
+    runServiceOverrides: Record<string, jest.Mock>,
+    // The chat assertOwnedChat resolves. Default: a chat OWNED by `user` (u1), so
+    // the ownership gate is transparent to the gate/CAS assertions below. Pass a
+    // foreign-owner (or undefined) chat to exercise the #487 owner rejection.
+    chat: { creatorId: string } | undefined = { creatorId: 'u1' },
+  ) {
+    const aiChatService = {
+      resolveRoleForRequest: jest.fn().mockResolvedValue(null),
+      getChatModel: jest.fn().mockResolvedValue({}),
+      stream: jest.fn().mockResolvedValue(undefined),
+    };
+    const aiChatRunService = {
+      getActiveForChat: jest.fn().mockResolvedValue(undefined),
+      supersede: jest.fn(),
+      beginRun: jest.fn().mockResolvedValue({
+        runId: 'run-new',
+        signal: new AbortController().signal,
+      }),
+      linkAssistantMessage: jest.fn(),
+      recordStep: jest.fn(),
+      finalizeRun: jest.fn(),
+      requestStop: jest.fn(),
+      ...runServiceOverrides,
+    };
+    const aiChatRepo = { findById: jest.fn().mockResolvedValue(chat) };
+    const controller = new AiChatController(
+      aiChatService as never,
+      aiChatRunService as never,
+      aiChatRepo as never, // aiChatRepo
+      {} as never, // aiChatMessageRepo
+      {} as never, // aiTranscription
+      {} as never, // pageRepo
+    );
+    return { controller, aiChatService, aiChatRunService, aiChatRepo };
+  }
+
+  const codeOf = (err: unknown) =>
+    (((err as HttpException).getResponse() as Record<string, unknown>) ?? {})
+      .code;
+
+  describe('single concurrency gate — BOTH modes reject the second tab with 409', () => {
+    for (const autonomousRuns of [true, false]) {
+      it(`rejects a concurrent start with 409 A_RUN_ALREADY_ACTIVE (autonomousRuns=${autonomousRuns})`, async () => {
+        const { controller, aiChatRunService } = makeController({
+          getActiveForChat: jest
+            .fn()
+            .mockResolvedValue({ id: 'run-live', chatId: 'c1' }),
+        });
+        const { req, res } = makeReqRes({ chatId: 'c1' });
+        let thrown: unknown;
+        try {
+          await controller.stream(
+            req as never,
+            res as never,
+            user,
+            wsWith(autonomousRuns),
+          );
+        } catch (e) {
+          thrown = e;
+        }
+        expect(thrown).toBeInstanceOf(ConflictException);
+        expect((thrown as HttpException).getStatus()).toBe(409);
+        expect(codeOf(thrown)).toBe('A_RUN_ALREADY_ACTIVE');
+        // Rejected BEFORE committing to the stream (no hijack, no service.stream).
+        expect(res.hijack).not.toHaveBeenCalled();
+        expect(aiChatRunService.getActiveForChat).toHaveBeenCalledWith(
+          'c1',
+          'ws1',
+        );
+      });
+    }
+  });
+
+  // #487 [security, F1]: stream() MUST owner-gate an existing chat exactly like its
+  // six sibling endpoints, BEFORE the supersede CAS. Otherwise a same-workspace
+  // non-owner could POST a supersede against another user's chat and (a) harvest
+  // that user's active runId from the 409 SUPERSEDE_TARGET_MISMATCH body, then (b)
+  // requestStop the foreign run. The gate must reject FIRST — no run lookup, no
+  // supersede, no stop, no runId leak.
+  describe('cross-user ownership gate (F1)', () => {
+    it('a non-owner streaming against someone else\'s chat is rejected (403) with NO runId leak and NO foreign requestStop', async () => {
+      // A live run exists on the victim's chat. Without the gate the supersede CAS
+      // would run and (faithful to the run service) return a MISMATCH carrying the
+      // victim's runId — the exact leak. With the gate it must never be reached.
+      const getActiveForChat = jest
+        .fn()
+        .mockResolvedValue({ id: 'run-victim', chatId: 'c-other' });
+      const supersede = jest
+        .fn()
+        .mockResolvedValue({ kind: 'mismatch', activeRunId: 'run-victim' });
+      const requestStop = jest.fn();
+      const { controller, aiChatService } = makeController(
+        { getActiveForChat, supersede, requestStop },
+        { creatorId: 'someone-else' }, // the chat is NOT owned by u1
+      );
+      const { req, res } = makeReqRes({
+        chatId: 'c-other',
+        supersede: { runId: 'guessed-uuid' },
+      });
+      let thrown: unknown;
+      try {
+        await controller.stream(req as never, res as never, user, wsWith(true));
+      } catch (e) {
+        thrown = e;
+      }
+      // Rejected by the ownership gate (403), the SAME shape the neighbors use.
+      expect(thrown).toBeInstanceOf(ForbiddenException);
+      expect((thrown as HttpException).getStatus()).toBe(403);
+      // Crucially NOT a 409 that would carry activeRunId — no runId is leaked.
+      const payload = JSON.stringify(
+        (thrown as HttpException).getResponse() ?? {},
+      );
+      expect(payload).not.toContain('run-victim');
+      expect(codeOf(thrown)).not.toBe('SUPERSEDE_TARGET_MISMATCH');
+      // The gate short-circuits BEFORE any run machinery runs.
+      expect(getActiveForChat).not.toHaveBeenCalled();
+      expect(supersede).not.toHaveBeenCalled();
+      expect(requestStop).not.toHaveBeenCalled();
+      expect(aiChatService.stream).not.toHaveBeenCalled();
+      expect(res.hijack).not.toHaveBeenCalled();
+    });
+  });
+
+  it('supersede MISMATCH -> 409 SUPERSEDE_TARGET_MISMATCH carrying the current runId', async () => {
+    const { controller } = makeController({
+      supersede: jest
+        .fn()
+        .mockResolvedValue({ kind: 'mismatch', activeRunId: 'run-other' }),
+    });
+    const { req, res } = makeReqRes({
+      chatId: 'c1',
+      supersede: { runId: 'run-x' },
+    });
+    let thrown: unknown;
+    try {
+      await controller.stream(req as never, res as never, user, wsWith(true));
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(ConflictException);
+    expect(codeOf(thrown)).toBe('SUPERSEDE_TARGET_MISMATCH');
+    expect(
+      ((thrown as HttpException).getResponse() as Record<string, unknown>)
+        .activeRunId,
+    ).toBe('run-other');
+    expect(res.hijack).not.toHaveBeenCalled();
+  });
+
+  it('supersede TIMEOUT -> 409 SUPERSEDE_TIMEOUT, nothing streamed', async () => {
+    const { controller } = makeController({
+      supersede: jest.fn().mockResolvedValue({ kind: 'timeout' }),
+    });
+    const { req, res } = makeReqRes({
+      chatId: 'c1',
+      supersede: { runId: 'run-x' },
+    });
+    let thrown: unknown;
+    try {
+      await controller.stream(req as never, res as never, user, wsWith(false));
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(ConflictException);
+    expect(codeOf(thrown)).toBe('SUPERSEDE_TIMEOUT');
+    expect(res.hijack).not.toHaveBeenCalled();
+  });
+
+  it('supersede INVALID (target on another chat) -> 400 SUPERSEDE_INVALID', async () => {
+    const { controller } = makeController({
+      supersede: jest.fn().mockResolvedValue({ kind: 'invalid' }),
+    });
+    const { req, res } = makeReqRes({
+      chatId: 'c1',
+      supersede: { runId: 'run-x' },
+    });
+    let thrown: unknown;
+    try {
+      await controller.stream(req as never, res as never, user, wsWith(true));
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(BadRequestException);
+    expect(codeOf(thrown)).toBe('SUPERSEDE_INVALID');
+  });
+
+  it('supersede without chatId -> 400 SUPERSEDE_INVALID', async () => {
+    const { controller, aiChatRunService } = makeController({});
+    const { req, res } = makeReqRes({ supersede: { runId: 'run-x' } });
+    let thrown: unknown;
+    try {
+      await controller.stream(req as never, res as never, user, wsWith(true));
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(BadRequestException);
+    expect(codeOf(thrown)).toBe('SUPERSEDE_INVALID');
+    expect(aiChatRunService.supersede).not.toHaveBeenCalled();
+  });
+
+  it('supersede READY -> proceeds to stream with superseded=true', async () => {
+    const { controller, aiChatService } = makeController({
+      supersede: jest.fn().mockResolvedValue({ kind: 'ready' }),
+      getActiveForChat: jest.fn().mockResolvedValue(undefined), // slot free after CAS
+    });
+    const { req, res } = makeReqRes({
+      chatId: 'c1',
+      supersede: { runId: 'run-x' },
+    });
+    await controller.stream(req as never, res as never, user, wsWith(true));
+    expect(res.hijack).toHaveBeenCalled();
+    expect(aiChatService.stream).toHaveBeenCalledTimes(1);
+    expect(aiChatService.stream.mock.calls[0][0].superseded).toBe(true);
+    // The run hooks are always present now (both modes).
+    expect(aiChatService.stream.mock.calls[0][0].runHooks).toBeDefined();
+  });
+
+  it('supersede DEGRADE -> proceeds to a normal send (superseded=false)', async () => {
+    const { controller, aiChatService } = makeController({
+      supersede: jest.fn().mockResolvedValue({ kind: 'degrade' }),
+    });
+    const { req, res } = makeReqRes({
+      chatId: 'c1',
+      supersede: { runId: 'run-x' },
+    });
+    await controller.stream(req as never, res as never, user, wsWith(false));
+    expect(aiChatService.stream).toHaveBeenCalledTimes(1);
+    expect(aiChatService.stream.mock.calls[0][0].superseded).toBe(false);
+  });
+});

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

@@ -418,6 +418,19 @@ export class AiChatController {
 
     const body = (req.body ?? {}) as AiChatStreamBody;
 
+    // #487 [security]: gate cross-user access to an EXISTING chat BEFORE anything
+    // reads its runs. Every sibling endpoint (getRun/stop/history/rename/delete/
+    // attachRunStream) owner-checks the chat via assertOwnedChat; stream() must too.
+    // Without this a same-workspace member who is NOT the chat owner could POST a
+    // supersede against another user's chat and (a) harvest that user's active runId
+    // out of the 409 SUPERSEDE_TARGET_MISMATCH body, then (b) requestStop the foreign
+    // run. Gate on the chatId the client sent, when present — a brand-new chat (no
+    // chatId) has no prior owner to check. Mirrors /stop's owner check (403 as the
+    // neighbors do), and runs pre-hijack so it returns clean JSON.
+    if (body.chatId) {
+      await this.assertOwnedChat(body.chatId, user, workspace);
+    }
+
     // Resolve the agent role for this turn BEFORE hijack: existing chats read it
     // from ai_chats.role_id (authoritative), a new chat from body.roleId. The
     // role drives both the persona and the optional model override below.
@@ -432,12 +445,66 @@ export class AiChatController {
     // HttpException) instead of breaking mid-stream.
     const model = await this.aiChatService.getChatModel(workspace.id, role);
 
-    // #184: one active run per chat. For an EXISTING chat reject a concurrent
-    // start with a clean 409 BEFORE hijack (the common double-submit / second-tab
-    // case), so the user gets JSON, not a mid-stream error. A brand-new chat
-    // (no chatId) cannot have a prior run, and the DB partial unique index is the
-    // backstop against any race that slips past this check.
-    if (autonomousRuns && body.chatId) {
+    // #487: server-side supersede CAS ("interrupt and send now"). When the client
+    // asks to replace a live run, atomically STOP it and wait for it to settle
+    // before this turn claims the slot. Runs BEFORE hijack so every branch returns
+    // clean JSON (the client keeps the composer text on a 409). See
+    // AiChatRunService.supersede for the branch semantics.
+    let superseded = false;
+    const supersedeRunId = body.supersede?.runId;
+    if (supersedeRunId) {
+      if (!body.chatId) {
+        throw new BadRequestException({
+          message: 'supersede requires chatId',
+          code: 'SUPERSEDE_INVALID',
+        });
+      }
+      const result = await this.aiChatRunService.supersede(
+        body.chatId,
+        supersedeRunId,
+        workspace.id,
+      );
+      switch (result.kind) {
+        case 'invalid':
+          throw new BadRequestException({
+            message: 'The run to supersede does not belong to this chat',
+            code: 'SUPERSEDE_INVALID',
+          });
+        case 'mismatch':
+          // A DIFFERENT run is active than the one the client targeted. Surface
+          // the CURRENT runId; the client does NOT auto-retry (a stale CAS).
+          throw new ConflictException({
+            message: 'A different agent run is now active on this chat',
+            code: 'SUPERSEDE_TARGET_MISMATCH',
+            activeRunId: result.activeRunId,
+          });
+        case 'timeout':
+          // The target did not settle within W — nothing was persisted, the
+          // composer keeps the text. NOT a rollback: the stop is already issued.
+          throw new ConflictException({
+            message:
+              'The previous run did not stop in time; nothing was sent — please try again',
+            code: 'SUPERSEDE_TIMEOUT',
+          });
+        case 'ready':
+          // The target stopped and settled: the slot is free. Prompt the new run
+          // that the old run's last operations may still be applying.
+          superseded = true;
+          break;
+        case 'degrade':
+          // The run already ended between click and POST — send normally.
+          break;
+      }
+    }
+
+    // #487: one active run per chat — ENFORCED IN BOTH MODES now (legacy mode used
+    // to have NO gate, so two tabs streamed two parallel turns on one chat, which
+    // interleaved history and crashed convertToModelMessages). Reject a concurrent
+    // start with a clean pre-hijack 409 (double-submit / second-tab). A brand-new
+    // chat (no chatId) cannot have a prior run, and the DB partial unique index in
+    // beginRun is the authoritative backstop for any race that slips past here
+    // (including a slot stolen between a supersede release and beginRun).
+    if (body.chatId) {
       const active = await this.aiChatRunService.getActiveForChat(
         body.chatId,
         workspace.id,
@@ -446,107 +513,94 @@ export class AiChatController {
         throw new ConflictException({
           message: 'An agent run is already in progress for this chat',
           code: 'A_RUN_ALREADY_ACTIVE',
+          activeRunId: active.id,
         });
       }
     }
 
-    // Run-lifecycle hooks (#184), only when the flag is on. They wrap the turn in
-    // a durable run whose abort is governed by the run (explicit stop), persist
-    // its progress, and settle its terminal status — see AiChatRunService.
-    const runHooks: AiChatRunHooks | undefined = autonomousRuns
-      ? {
-          begin: async (chatId) => {
-            const handle = await this.aiChatRunService.beginRun({
-              chatId,
-              workspaceId: workspace.id,
-              userId: user.id,
-              trigger: 'user',
-            });
-            // #184 phase 1.5: register the run-stream entry at BEGIN (before any
-            // frame) so a tab that attaches in the begin->seed window finds an
-            // entry to wait on. Gated on AI_CHAT_RESUMABLE_STREAM: with the flag
-            // off nothing is registered and attach always 204s.
-            if (
-              handle?.runId &&
-              this.environment?.isAiChatResumableStreamEnabled?.()
-            ) {
-              this.streamRegistry?.open(chatId, handle.runId);
-            }
-            return handle;
-          },
-          onAssistantSeeded: (runId, messageId) =>
-            this.aiChatRunService.linkAssistantMessage(
-              runId,
-              workspace.id,
-              messageId,
-            ),
-          onStep: (runId, stepCount) =>
-            void this.aiChatRunService.recordStep(
-              runId,
-              workspace.id,
-              stepCount,
-            ),
-          onSettled: (runId, status, error) =>
-            this.aiChatRunService.finalizeRun(
-              runId,
-              workspace.id,
-              status,
-              error,
-            ),
+    // #487: the turn is ALWAYS a first-class RUN now (both modes). The mode
+    // difference is only the abort semantics on a browser disconnect (onClose
+    // below). currentRunId is captured at begin so a legacy disconnect can stop
+    // the run through its stop lever.
+    let currentRunId: string | undefined;
+    const runHooks: AiChatRunHooks = {
+      begin: async (chatId) => {
+        const handle = await this.aiChatRunService.beginRun({
+          chatId,
+          workspaceId: workspace.id,
+          userId: user.id,
+          trigger: 'user',
+        });
+        currentRunId = handle?.runId;
+        // #184 phase 1.5: register the run-stream entry at BEGIN (before any
+        // frame) so a tab that attaches in the begin->seed window finds an entry
+        // to wait on. Gated on AI_CHAT_RESUMABLE_STREAM.
+        if (
+          handle?.runId &&
+          this.environment?.isAiChatResumableStreamEnabled?.()
+        ) {
+          this.streamRegistry?.open(chatId, handle.runId);
         }
-      : undefined;
+        return handle;
+      },
+      onAssistantSeeded: (runId, messageId) =>
+        this.aiChatRunService.linkAssistantMessage(
+          runId,
+          workspace.id,
+          messageId,
+        ),
+      onStep: (runId, stepCount) =>
+        void this.aiChatRunService.recordStep(runId, workspace.id, stepCount),
+      onSettled: (runId, status, error) =>
+        this.aiChatRunService.finalizeRun(runId, workspace.id, status, error),
+    };
 
-    // Abort the agent loop when the client disconnects. `close` also fires on
-    // normal completion, so only abort when the response has not finished
-    // writing (a genuine disconnect). `once` fires at most once and self-removes;
-    // we also drop it on response `finish` so it never lingers after the stream
-    // completes normally (the AI SDK pipes the response fire-and-forget, so we
-    // cannot simply remove it once `stream()` returns).
+    // Handle a client disconnect. `close` also fires on normal completion, so only
+    // act when the response has not finished writing (a genuine disconnect). `once`
+    // fires at most once and self-removes; we also drop it on response `finish`.
     // DIAGNOSTIC (Safari stream-drop investigation) — temporary: wall-clock at
     // which a Safari disconnect is observed, measured from request receipt.
     const reqStartedAt = Date.now();
     const controller = new AbortController();
     const onClose = (): void => {
-      // A genuine disconnect leaves the response unfinished (unlike a normal
-      // completion, which also fires `close`). Such a drop — e.g. a reverse
-      // proxy cutting the SSE mid-answer — is otherwise invisible server-side,
-      // so log it here.
       if (!res.raw.writableEnded) {
         if (autonomousRuns) {
-          // #184: the turn is a DETACHED run. A disconnect must NOT abort it —
-          // the run keeps executing and persisting server-side; the client
-          // reconnects via /ai-chat/run (or re-stops via /ai-chat/stop). Log only.
+          // #184: a DETACHED run — a disconnect must NOT stop it. The run keeps
+          // executing and persisting server-side; the client reconnects via
+          // /ai-chat/run (or re-stops via /ai-chat/stop). Log only.
           this.logger.log(
             `AI chat stream: client disconnected; run continues server-side ` +
               `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
           );
         } else {
+          // #487: legacy — a disconnect ENDS the turn, but the turn is now a RUN,
+          // so stop it through the run's stop lever (requestStop). streamText no
+          // longer consumes the socket signal (effectiveSignal is the run signal),
+          // so aborting `controller` would do nothing; requestStop aborts the run.
           this.logger.warn(
-            `AI chat stream: client disconnected before completion; aborting turn ` +
-              `(elapsed=${Date.now() - reqStartedAt}ms since request received)`,
+            `AI chat stream: client disconnected before completion; stopping the ` +
+              `run (elapsed=${Date.now() - reqStartedAt}ms since request received)`,
           );
-          controller.abort();
+          if (currentRunId) {
+            void this.aiChatRunService.requestStop(currentRunId, workspace.id);
+          }
         }
       }
     };
     req.raw.once('close', onClose);
     res.raw.once('finish', () => req.raw.off('close', onClose));
 
-    // #184: in detached mode the turn is NOT aborted on disconnect, so the SDK's
-    // pipe keeps writing to a socket the client may have dropped — for the rest of
-    // the (continuing) run. A write to the dead socket can emit an 'error' on the
-    // raw response; without a listener that surfaces as an unhandled error event.
-    // Swallow it (the run continues server-side regardless). Legacy mode aborts on
-    // disconnect, so it does not need this and keeps its exact prior behavior.
-    if (autonomousRuns) {
-      res.raw.on('error', (err) => {
-        this.logger.debug(
-          `AI chat detached stream: post-disconnect socket error swallowed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-      });
-    }
+    // #184/#487: the run/pipe can outlive the socket in BOTH modes now (autonomous
+    // keeps going; legacy keeps going until requestStop's abort unwinds the turn).
+    // The SDK's pipe may then write to a dropped socket and emit an 'error' on the
+    // raw response — swallow it so it never surfaces as an unhandled error event.
+    res.raw.on('error', (err) => {
+      this.logger.debug(
+        `AI chat stream: post-disconnect socket error swallowed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
 
     // Commit to streaming: hijack so Fastify stops managing the response and
     // the AI SDK can write the UI-message stream directly to the Node socket.
@@ -562,8 +616,10 @@ export class AiChatController {
         signal: controller.signal,
         model,
         role,
-        // #184: present only when the flag is on; wraps the turn in a durable run.
+        // #487: the turn is always run-wrapped now (both modes).
         runHooks,
+        // #487: warn the new run that a superseded run's last ops may still apply.
+        superseded,
       });
     } catch (err) {
       // Any failure AFTER hijack can no longer go through Nest's exception

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

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

apps/server/src/core/ai-chat/ai-chat.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
@@ -77,6 +101,22 @@ const INTERRUPT_NOTE =
   'assume your previous response was complete, and do not silently restart the ' +
   'partial work — build on it or follow the new instruction.';
 
+/**
+ * #487: injected on a turn started by SUPERSEDING a previous run (the user hit
+ * "interrupt and send now" while a run was live). The previous run was Stopped,
+ * but there is NO side-effect quiescence — a write it had already committed, or
+ * one committing at the moment of Stop, may land with a small delay AFTER this new
+ * run starts. So the model is told its picture of the page/state may be a beat
+ * stale and to re-read before assuming an edit did or did not apply.
+ */
+const SUPERSEDE_NOTE =
+  'NOTE: A previous agent run in this conversation was just interrupted so this ' +
+  'new turn could start. That run was stopped, but any operation it had already ' +
+  'begun (e.g. a page edit) may still be applied with a short delay. Do not ' +
+  'assume the document/state is exactly as the interrupted run left it — if you ' +
+  'need to rely on the current content, RE-READ it with the page tools before ' +
+  'acting rather than trusting a cached view.';
+
 /**
  * Injected on a turn where the open page was hand-edited by the user (or anyone
  * else) AFTER the agent's previous response ended (#274). The server takes a
@@ -91,15 +131,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.';
 
 /**
@@ -179,6 +219,14 @@ export interface BuildSystemPromptInput {
    * (partial) answer was cut off by the user's new message.
    */
   interrupted?: boolean;
+  /**
+   * #487: true when THIS turn was started by superseding a still-live previous run
+   * ("interrupt and send now"). Adds SUPERSEDE_NOTE so the model knows the previous
+   * run's last operations may still be applying and to re-read state it depends on.
+   * Distinct from `interrupted` (which is about a PARTIAL prior answer in history);
+   * both can be set together. Self-clears — set only for the superseding turn.
+   */
+  superseded?: boolean;
   /**
    * Set only when the open page was edited by the user AFTER the agent's previous
    * turn ended (#274), confirmed server-side by diffing the current page against
@@ -224,8 +272,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 +285,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>',
@@ -283,6 +335,7 @@ export function buildSystemPrompt({
   openedPage,
   mcpInstructions,
   interrupted,
+  superseded,
   pageChanged,
   deferredToolsEnabled,
   toolCatalog,
@@ -332,6 +385,13 @@ export function buildSystemPrompt({
     context += `\n${INTERRUPT_NOTE}`;
   }
 
+  // Supersede note (#487): present only for a turn that stopped and replaced a
+  // still-live previous run — warns the model the previous run's last operations
+  // may still be applying (no side-effect quiescence).
+  if (superseded) {
+    context += `\n${SUPERSEDE_NOTE}`;
+  }
+
   // Per-turn page-change note (#274). Added to the context section (inside the
   // safety sandwich), present only when the server detected that the open page
   // was edited by the user since the agent's last turn ended. The diff content is

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

@@ -89,11 +89,22 @@ describe('AiChatService.stream run-lifecycle safety net (#184)', () => {
     const runRepo = {
       insert: jest.fn().mockResolvedValue({ id: 'run-1', status: 'running' }),
       update: jest.fn().mockResolvedValue({ id: 'run-1' }),
+      // #487: the terminal settle now goes through the CONDITIONAL write.
+      finalizeIfActive: jest
+        .fn()
+        .mockResolvedValue({ id: 'run-1', status: 'failed' }),
+      findById: jest.fn().mockResolvedValue(undefined),
     };
     const runService = new AiChatRunService(runRepo as never, { isCloud: () => false } as never);
 
-    // The user-message insert (the first bare await after beginRun) throws.
+    // The user-message insert throws. #489 runs the history load + convert BEFORE
+    // the insert (convert-before-insert, so a retry cannot duplicate the user row),
+    // so `findAllByChat` (a real repo method) is now called first — stub it to an
+    // empty history so the flow reaches the insert. Both awaits are AFTER beginRun,
+    // so the "exception after beginRun -> settled to error" invariant is unchanged;
+    // the throw point simply moved from insert to a later insert after a no-op load.
     const aiChatMessageRepo = {
+      findAllByChat: jest.fn().mockResolvedValue([]),
       insert: jest.fn().mockRejectedValue(new Error('insert boom')),
     };
     const aiChatRepo = {
@@ -148,9 +159,10 @@ describe('AiChatService.stream run-lifecycle safety net (#184)', () => {
 
     // The run was begun...
     expect(runRepo.insert).toHaveBeenCalledTimes(1);
-    // ...then settled to a terminal FAILED status by the safety net...
-    expect(runRepo.update).toHaveBeenCalledTimes(1);
-    expect(runRepo.update).toHaveBeenCalledWith(
+    // ...then settled to a terminal FAILED status by the safety net (via the
+    // #487 conditional write)...
+    expect(runRepo.finalizeIfActive).toHaveBeenCalledTimes(1);
+    expect(runRepo.finalizeIfActive).toHaveBeenCalledWith(
       'run-1',
       'ws1',
       expect.objectContaining({ status: 'failed' }),

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 };
@@ -151,6 +155,8 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       insert: jest.fn(async () => ({ id: 'msg-1' })),
       findAllByChat: jest.fn(async () => []),
       update: jest.fn(async () => ({ id: 'msg-1' })),
+      finalizeOwner: jest.fn(async () => ({ id: 'msg-1' })),
+      findStreamingWithTerminalRun: jest.fn(async () => []),
     };
     const aiSettings = { resolve: jest.fn(async () => ({})) };
     const tools = { forUser: jest.fn(async () => ({})) };
@@ -173,7 +179,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 +205,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 +230,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 +264,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);
   });
 
   /**
@@ -309,7 +334,13 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       usage: {},
       steps: [],
     });
-    expect(runHooks.onSettled).toHaveBeenCalledWith('run-1', 'completed');
+    // #487: onFinish passes the (undefined) error slot so a message-finalize
+    // failure could error-mark the run; on the success path it is undefined.
+    expect(runHooks.onSettled).toHaveBeenCalledWith(
+      'run-1',
+      'completed',
+      undefined,
+    );
   });
 
   it('F9: onAbort settles the run "aborted"', async () => {
@@ -341,22 +372,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() {
@@ -392,6 +423,8 @@ describe('AiChatService.stream — begin-failure resilience / legacy fallback (#
       insert: jest.fn(async () => ({ id: 'msg-1' })),
       findAllByChat: jest.fn(async () => []),
       update: jest.fn(async () => ({ id: 'msg-1' })),
+      finalizeOwner: jest.fn(async () => ({ id: 'msg-1' })),
+      findStreamingWithTerminalRun: jest.fn(async () => []),
     };
     const aiSettings = { resolve: jest.fn(async () => ({})) };
     const tools = { forUser: jest.fn(async () => ({})) };
@@ -414,7 +447,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 +469,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 +501,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);
   });
 });
 
@@ -1208,8 +1315,12 @@ describe('AiChatService page-change lifecycle (#274)', () => {
 describe('isInterruptResume', () => {
   // history tail is the just-inserted user row; [len-2] is the previous turn.
   const withPrev = (
-    prev: { role: string; status?: string | null } | null,
-  ): Array<{ role: string; status?: string | null }> =>
+    prev: {
+      role: string;
+      status?: string | null;
+      metadata?: unknown;
+    } | null,
+  ): Array<{ role: string; status?: string | null; metadata?: unknown }> =>
     prev
       ? [prev, { role: 'user', status: null }]
       : [{ role: 'user', status: null }];
@@ -1250,6 +1361,33 @@ describe('isInterruptResume', () => {
   it('false when there is no preceding turn (only the new user row)', () => {
     expect(isInterruptResume(withPrev(null), true)).toBe(false);
   });
+
+  it('#487 EXCLUDES a reconcile stamp (finalizeFailed) — not a genuine interruption', () => {
+    // A row a reconcile settled to 'aborted' carries metadata.finalizeFailed. It
+    // must NOT be treated as an interrupt-resume (that would inject a false
+    // "you were interrupted" note), even though its status is 'aborted'.
+    expect(
+      isInterruptResume(
+        withPrev({
+          role: 'assistant',
+          status: 'aborted',
+          metadata: { finalizeFailed: true },
+        }),
+        true,
+      ),
+    ).toBe(false);
+    // A genuine abort (no finalizeFailed) still counts.
+    expect(
+      isInterruptResume(
+        withPrev({
+          role: 'assistant',
+          status: 'aborted',
+          metadata: { parts: [] },
+        }),
+        true,
+      ),
+    ).toBe(true);
+  });
 });
 
 /**
@@ -1302,7 +1440,7 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
   }
 
   // Wire only the deps reached on the way to the pipe call, plus a spy registry.
-  function makeService(opts: { resumable: boolean }) {
+  function makeService(opts: { resumable: boolean; history?: unknown[] }) {
     const aiChatRepo = {
       findById: jest.fn(async () => ({ id: 'chat-1', workspaceId: 'ws-1' })),
       insert: jest.fn(),
@@ -1310,8 +1448,11 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
     const aiChatMessageRepo = {
       // Both the user insert and the assistant seed return the same row id.
       insert: jest.fn(async () => ({ id: 'msg-1' })),
-      findAllByChat: jest.fn(async () => []),
+      findAllByChat: jest.fn(async () => opts.history ?? []),
       update: jest.fn(async () => ({ id: 'msg-1' })),
+      // #487: the terminal owner-write + the opportunistic reconcile query.
+      finalizeOwner: jest.fn(async () => ({ id: 'msg-1' })),
+      findStreamingWithTerminalRun: jest.fn(async () => []),
     };
     const aiSettings = { resolve: jest.fn(async () => ({})) };
     const tools = { forUser: jest.fn(async () => ({})) };
@@ -1341,11 +1482,12 @@ 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,
     );
-    return { svc, streamRegistry };
+    return { svc, streamRegistry, aiChatMessageRepo };
   }
 
   const body = {
@@ -1428,4 +1570,587 @@ describe('AiChatService.stream — resumable pipe options (#184 phase 1.5)', ()
     await expect(drive(svc, makeRunHooks())).rejects.toThrow('boom');
     expect(streamRegistry.abortEntry).toHaveBeenCalledWith('chat-1', 'run-1');
   });
+
+  // #489 REGRESSION (against the REAL convertToModelMessages — not mocked here):
+  // a persisted history row whose parts contain a `null` element makes the real
+  // convertToModelMessages THROW ("Cannot read properties of null"). Pre-fix that
+  // 500-ed every turn forever and each retry appended a duplicate user row. The
+  // fix converts BEFORE the insert and isolates the poisoned row per-row, degrading
+  // it to text with a "[tool context omitted]" marker. Assert the turn still runs,
+  // the marker reaches the model, and exactly ONE user row is inserted.
+  it('#489: a poisoned OLD-history row keeps the chat working; the marker reaches the model; one user insert', async () => {
+    const { svc, aiChatMessageRepo } = makeService({
+      resumable: false,
+      history: [
+        {
+          id: 'old-1',
+          role: 'assistant',
+          content: 'earlier answer',
+          // A null part is the poison: rowToUiMessage keeps it (the array is
+          // non-empty) and the real convertToModelMessages throws on it.
+          metadata: { parts: [{ type: 'text', text: 'earlier answer' }, null] },
+          status: 'completed',
+        },
+      ],
+    });
+    // Must NOT throw — the poisoned row is degraded, not fatal.
+    await drive(svc, makeRunHooks());
+    expect(streamTextMock).toHaveBeenCalledTimes(1);
+    const passedMessages = streamTextMock.mock.calls[0][0].messages;
+    const serialized = JSON.stringify(passedMessages);
+    // The model sees the truncation marker (silent tool-context loss is not ok)
+    // AND the row's readable text is preserved alongside it.
+    expect(serialized).toContain('[tool context omitted]');
+    expect(serialized).toContain('earlier answer');
+    // Exactly ONE user row inserted (no duplicate), inserted AFTER conversion.
+    const userInserts = aiChatMessageRepo.insert.mock.calls
+      .map((c: unknown[]) => c[0] as { role?: string })
+      .filter((r) => r.role === 'user');
+    expect(userInserts).toHaveLength(1);
+  });
+
+  // #489: client-supplied non-text parts (a tool-part in `input-available`, the
+  // exact "bricking" payload) are dropped ON RECEIPT — never persisted — so they
+  // can never poison future turns. Only the text survives into metadata.parts.
+  it('#489: a non-text client part is stripped before persist (only text survives)', async () => {
+    const { svc, aiChatMessageRepo } = makeService({ resumable: false });
+    await svc.stream({
+      user: { id: 'u1' } as never,
+      workspace: { id: 'ws-1' } as never,
+      sessionId: 's1',
+      body: {
+        chatId: 'chat-1',
+        messages: [
+          {
+            id: 'm1',
+            role: 'user',
+            parts: [
+              { type: 'text', text: 'hello' },
+              // untrusted tool-part — must be dropped, never persisted
+              {
+                type: 'tool-getPage',
+                toolCallId: 't1',
+                state: 'input-available',
+                input: { pageId: 'p' },
+              },
+            ],
+          },
+        ],
+      } as never,
+      res: makeRes() as never,
+      signal: new AbortController().signal,
+      model: {} as never,
+      role: null,
+      runHooks: makeRunHooks() as never,
+    });
+    const userInsert = aiChatMessageRepo.insert.mock.calls
+      .map((c: unknown[]) => c[0] as { role?: string; metadata?: unknown })
+      .find((r) => r.role === 'user');
+    const parts = (userInsert?.metadata as { parts?: Array<{ type: string }> })
+      ?.parts;
+    expect(parts).toEqual([{ type: 'text', text: 'hello' }]);
+  });
+});
+
+/**
+ * #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 };
+        },
+      ),
+      // #487: the terminal owner-write records into the SAME `updated` recorder so
+      // assertions on the terminal 'completed'/'error'/'aborted' write still hold.
+      finalizeOwner: jest.fn(
+        async (
+          id: string,
+          workspaceId: string,
+          patch: Record<string, unknown>,
+        ) => {
+          updated.push({ id, workspaceId, patch });
+          return { id };
+        },
+      ),
+      findStreamingWithTerminalRun: jest.fn(async () => []),
+    };
+    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);
+  });
+});
+
+// #487 F3 — the reconcile() / reconcileChat() ORCHESTRATORS. The individual
+// clauses are exercised elsewhere; these pin the production orchestration the
+// per-clause specs do not: the clause ORDER, the per-clause try/catch ISOLATION
+// (one clause throwing must NOT abort the others), and reconcileChat() (which runs
+// at the start of every turn and was entirely uncovered).
+describe('AiChatService.reconcile / reconcileChat orchestrators (#487 F3)', () => {
+  let warnSpy: jest.SpyInstance;
+  beforeEach(() => {
+    // Silence the intentional clause-failure warnings (kept out of test output).
+    warnSpy = jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined);
+  });
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  function makeService(opts: {
+    messageRepo?: Record<string, jest.Mock>;
+    runService?: Record<string, jest.Mock>;
+  }) {
+    const aiChatMessageRepo = {
+      findStreamingWithTerminalRun: jest.fn(async () => []),
+      stampTerminalIfStreaming: jest.fn(async () => undefined),
+      sweepStreamingWithoutActiveRun: jest.fn(async () => 0),
+      ...(opts.messageRepo ?? {}),
+    };
+    const aiChatRunService = opts.runService
+      ? {
+          zombieRunIds: jest.fn(() => []),
+          settleZombie: jest.fn(async () => true),
+          reconcileStaleRuns: jest.fn(async () => 0),
+          ...opts.runService,
+        }
+      : undefined;
+    const svc = new AiChatService(
+      {} as never, // ai
+      {} as never, // aiChatRepo
+      aiChatMessageRepo as never,
+      {} as never, // aiChatPageSnapshotRepo
+      {} as never, // aiSettings
+      {} as never, // tools
+      {} as never, // mcpClients
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo
+      {} as never, // pageAccess
+      {} as never, // environment
+      {} as never, // streamRegistry
+      aiChatRunService as never, // aiChatRunService (#487)
+    );
+    return { svc, aiChatMessageRepo, aiChatRunService };
+  }
+
+  it('reconcile() fires all four clauses IN ORDER (a -> b -> c -> d)', async () => {
+    const order: string[] = [];
+    const { svc } = makeService({
+      messageRepo: {
+        findStreamingWithTerminalRun: jest.fn(async () => {
+          order.push('b:find');
+          return [
+            { messageId: 'm1', workspaceId: 'ws1', runStatus: 'succeeded' },
+          ];
+        }),
+        stampTerminalIfStreaming: jest.fn(async () => {
+          order.push('b:stamp');
+        }),
+        sweepStreamingWithoutActiveRun: jest.fn(async () => {
+          order.push('d');
+          return 0;
+        }),
+      },
+      runService: {
+        zombieRunIds: jest.fn(() => ['z1']),
+        settleZombie: jest.fn(async () => {
+          order.push('a');
+          return true;
+        }),
+        reconcileStaleRuns: jest.fn(async () => {
+          order.push('c');
+          return 0;
+        }),
+      },
+    });
+
+    await svc.reconcile();
+
+    expect(order).toEqual(['a', 'b:find', 'b:stamp', 'c', 'd']);
+  });
+
+  it('a clause that THROWS does not abort the remaining clauses (per-clause try/catch isolation)', async () => {
+    const { svc, aiChatMessageRepo, aiChatRunService } = makeService({
+      messageRepo: {
+        // Clause (b) blows up mid-reconcile.
+        findStreamingWithTerminalRun: jest.fn(async () => {
+          throw new Error('clause b DB blip');
+        }),
+      },
+      runService: {
+        zombieRunIds: jest.fn(() => ['z1']),
+      },
+    });
+
+    // reconcile() must SETTLE (the clause-b failure is swallowed), not reject.
+    await expect(svc.reconcile()).resolves.toBeUndefined();
+
+    // (a) ran before (b); crucially (c) and (d) STILL ran despite (b) throwing —
+    // the property a missing try/catch would break. MUTATION-VERIFY: drop clause
+    // (b)'s try/catch and this reddens (the throw propagates, skipping c + d).
+    expect(aiChatRunService!.settleZombie).toHaveBeenCalled(); // (a)
+    expect(aiChatRunService!.reconcileStaleRuns).toHaveBeenCalled(); // (c)
+    expect(
+      aiChatMessageRepo.sweepStreamingWithoutActiveRun,
+    ).toHaveBeenCalled(); // (d)
+  });
+
+  it('reconcileChat() settles THIS chat\'s stuck streaming rows by their run status', async () => {
+    const { svc, aiChatMessageRepo } = makeService({
+      messageRepo: {
+        findStreamingWithTerminalRun: jest.fn(async () => [
+          { messageId: 'm1', workspaceId: 'ws1', runStatus: 'failed' },
+          { messageId: 'm2', workspaceId: 'ws1', runStatus: 'succeeded' },
+        ]),
+      },
+    });
+
+    await svc.reconcileChat('chat-1', 'ws1');
+
+    // Scoped to THIS chat and bounded at 50 (the user-facing opportunistic path).
+    expect(
+      aiChatMessageRepo.findStreamingWithTerminalRun,
+    ).toHaveBeenCalledWith(50, { chatId: 'chat-1', workspaceId: 'ws1' });
+    // failed-run -> 'error'; every other terminal status -> 'aborted'.
+    expect(aiChatMessageRepo.stampTerminalIfStreaming).toHaveBeenCalledWith(
+      'm1',
+      'ws1',
+      'error',
+    );
+    expect(aiChatMessageRepo.stampTerminalIfStreaming).toHaveBeenCalledWith(
+      'm2',
+      'ws1',
+      'aborted',
+    );
+  });
 });

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/external-mcp/mcp-clients.recovery.spec.ts

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

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

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

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

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

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

@@ -0,0 +1,444 @@
+import { Logger } from '@nestjs/common';
+import { streamText } from 'ai';
+import {
+  hasRepeatedLineRun,
+  hasPeriodicTail,
+  isDegenerateOutput,
+  truncateDegeneratedTail,
+  shouldCheckDegeneration,
+  DEGENERATION_CHECK_STEP,
+  REPEATED_LINES_THRESHOLD,
+  MIN_PERIOD_REPEATS,
+  degenerationThresholds,
+} from './output-degeneration';
+import { AiChatService } from './ai-chat.service';
+
+// Part A (#495 iter10): the detector thresholds are env-tunable. These drive the
+// resolver against real repeat-count shapes and mutation-verify that the env
+// override actually changes the trigger point (not a vacuous read).
+describe('degeneration thresholds are env-configurable', () => {
+  const VARS = [
+    'AI_CHAT_DEGENERATION_REPEATED_LINES',
+    'AI_CHAT_DEGENERATION_PERIOD_MAX_LEN',
+    'AI_CHAT_DEGENERATION_PERIOD_MIN_REPEATS',
+    'AI_CHAT_DEGENERATION_CHECK_STEP',
+  ];
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const v of VARS) saved[v] = process.env[v];
+  });
+  afterEach(() => {
+    for (const v of VARS) {
+      if (saved[v] === undefined) delete process.env[v];
+      else process.env[v] = saved[v];
+    }
+  });
+
+  it('defaults to the compiled constants when unset', () => {
+    for (const v of VARS) delete process.env[v];
+    expect(degenerationThresholds()).toEqual({
+      repeatedLines: REPEATED_LINES_THRESHOLD,
+      maxPeriodLen: 150,
+      minPeriodRepeats: MIN_PERIOD_REPEATS,
+      checkStep: DEGENERATION_CHECK_STEP,
+    });
+  });
+
+  it('falls back to the default on blank / invalid / non-positive values', () => {
+    for (const bad of ['', '  ', 'abc', '0', '-3', '1.5']) {
+      process.env.AI_CHAT_DEGENERATION_REPEATED_LINES = bad;
+      // '1.5' floors to 1 (still ≥1, valid); every other bad value → default.
+      const expected = bad === '1.5' ? 1 : REPEATED_LINES_THRESHOLD;
+      expect(degenerationThresholds().repeatedLines).toBe(expected);
+    }
+  });
+
+  it('a RAISED check-step suppresses a burst the default would have flagged', () => {
+    // A ~3.3KB periodic burst is periodic-degenerate, but shouldCheckDegeneration
+    // is the throttle gate. Default checkStep=2000 arms on it; raising the step
+    // above the burst size means the throttle never re-fires for it.
+    const burstLen = 'loadTools.\n'.repeat(300).length; // ~3300
+    delete process.env.AI_CHAT_DEGENERATION_CHECK_STEP;
+    expect(shouldCheckDegeneration(burstLen, 0)).toBe(true); // default 2000
+    process.env.AI_CHAT_DEGENERATION_CHECK_STEP = String(burstLen + 1);
+    expect(shouldCheckDegeneration(burstLen, 0)).toBe(false); // raised gate
+  });
+
+  it('a LOWERED repeated-lines threshold trips on a shorter identical-line run', () => {
+    // 8 identical lines: below the default 25 (rule 1) and below the periodic
+    // rule's 20 repeats — so isDegenerateOutput is false by default.
+    const shortRun = 'x\n'.repeat(8);
+    delete process.env.AI_CHAT_DEGENERATION_REPEATED_LINES;
+    expect(isDegenerateOutput(shortRun)).toBe(false);
+    // Lower rule 1 to 5 → the 8-line run now trips.
+    process.env.AI_CHAT_DEGENERATION_REPEATED_LINES = '5';
+    expect(isDegenerateOutput(shortRun)).toBe(true);
+  });
+});
+
+// Mock ONLY streamText so we can capture the onChunk/onStepFinish callbacks the
+// service registers and drive them by hand; every other `ai` export the service
+// uses (convertToModelMessages, stepCountIs, …) stays real.
+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,267 @@
+/**
+ * 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;
+
+/**
+ * Read a positive-integer threshold from an env var, falling back to `fallback`
+ * on unset/blank/invalid/non-positive. Mirrors the `AI_STREAM_PRE_RESPONSE_RETRIES`
+ * resolver in `ai-streaming-fetch.ts`: read the RAW string first so a blank value
+ * is treated as "unset" (→ fallback) rather than coercing to 0. Thresholds must
+ * stay ≥ 1 — a 0/negative would make the detector fire on any text (or never), so
+ * a bad value degrades to the safe compiled default instead. Env-tunable so an
+ * operator can retune the anti-babble guard (#444) without a redeploy, following
+ * the `AI_CHAT_FINAL_STEP_LOCKDOWN` toggle convention.
+ */
+function envThreshold(name: string, fallback: number): number {
+  const rawStr = process.env[name];
+  if (rawStr === undefined || rawStr.trim() === '') return fallback;
+  const raw = Number(rawStr);
+  return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : fallback;
+}
+
+/**
+ * Resolve the degeneration-detector thresholds from the environment, each
+ * defaulting to the compiled constant above. Read fresh per call (not cached at
+ * import) so a test — or a runtime env change — takes effect deterministically.
+ */
+export function degenerationThresholds(): {
+  repeatedLines: number;
+  maxPeriodLen: number;
+  minPeriodRepeats: number;
+  checkStep: number;
+} {
+  return {
+    repeatedLines: envThreshold(
+      'AI_CHAT_DEGENERATION_REPEATED_LINES',
+      REPEATED_LINES_THRESHOLD,
+    ),
+    maxPeriodLen: envThreshold(
+      'AI_CHAT_DEGENERATION_PERIOD_MAX_LEN',
+      MAX_PERIOD_LEN,
+    ),
+    minPeriodRepeats: envThreshold(
+      'AI_CHAT_DEGENERATION_PERIOD_MIN_REPEATS',
+      MIN_PERIOD_REPEATS,
+    ),
+    checkStep: envThreshold(
+      'AI_CHAT_DEGENERATION_CHECK_STEP',
+      DEGENERATION_CHECK_STEP,
+    ),
+  };
+}
+
+/**
+ * Rule 1 — ≥`REPEATED_LINES_THRESHOLD` consecutive IDENTICAL non-empty lines at
+ * the tail. Catches the classic newline-delimited loop ("loadTools.\n" ×N).
+ * 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 {
+  const cfg = degenerationThresholds();
+  return (
+    hasRepeatedLineRun(text, cfg.repeatedLines) ||
+    hasPeriodicTail(text, cfg.maxPeriodLen, cfg.minPeriodRepeats)
+  );
+}
+
+/**
+ * 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 >= degenerationThresholds().checkStep;
+}
+
+/**
+ * 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.
  *
@@ -280,6 +307,10 @@ export class PublicShareChatService {
         system,
         messages: modelMessages,
         tools,
+        // Pin the AI SDK per-request retry budget explicitly (matches the SDK
+        // default of 2). Connection arithmetic: (1 + maxRetries) × (1 +
+        // AI_STREAM_PRE_RESPONSE_RETRIES) worst-case connects per turn.
+        maxRetries: 2,
         // Bound the agent loop for anonymous callers.
         stopWhen: stepCountIs(5),
         // Cap per-request output so one anonymous call cannot run up the provider
@@ -318,11 +349,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/public-share-chat.spec.ts

@@ -808,7 +808,7 @@ describe('PublicShareChatToolsService share scoping', () => {
     };
 
     await expect(getSharePage.execute({ pageId: 'p-outside' })).rejects.toThrow(
-      /not part of this published share/i,
+      /not available in this share/i,
     );
     // The tool delegated the resolve to the canonical boundary with the
     // forShare-scoped shareId, and returned NO content for a non-resolving page.
@@ -841,7 +841,7 @@ describe('PublicShareChatToolsService share scoping', () => {
 
     await expect(
       getSharePage.execute({ pageId: 'p-restricted' }),
-    ).rejects.toThrow(/not part of this published share/i);
+    ).rejects.toThrow(/not available in this share/i);
     // No content was ever sanitized/returned for the blocked page.
     expect(shareService.updatePublicAttachments).not.toHaveBeenCalled();
   });
@@ -1003,7 +1003,7 @@ describe('public-share assistant boundary locks (red-team regression guards)', (
     };
     await expect(
       getSharePage.execute({ pageId: 'p-elsewhere' }),
-    ).rejects.toThrow(/not part of this published share/i);
+    ).rejects.toThrow(/not available in this share/i);
     // The forged share id is the scope the boundary re-derivation rejects against.
     expect(shareService.resolveReadableSharePage).toHaveBeenCalledWith(
       'FORGED-SHARE',

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

@@ -0,0 +1,160 @@
+import {
+  wrapInAppToolWithCap,
+  inAppToolCallCapMs,
+  type ToolAbortSignalSink,
+} from './ai-chat-tools.service';
+import type { Tool, ToolCallOptions } from 'ai';
+
+/**
+ * #487 commit 1 — in-app tool race-on-abort + safe-points + per-call cap.
+ *
+ * Tests assert the HONEST observable property the spec names — "after Stop, NO
+ * new HTTP/WS call STARTS; an already-started single call may take either
+ * outcome" — against the REAL wrapper mechanism (the composite abort signal it
+ * publishes on the client + the RACE it runs), NOT a timing-dependent proxy like
+ * "the write didn't land".
+ */
+
+// A minimal stand-in for the client's `toolAbortSignal` field. In production the
+// wrapper publishes the composite here and the client's paginateAll /
+// mutatePageContent safe-points read it; the fake "tool" below reads it the same
+// way, so this exercises the real contract without a live DB / collab socket.
+class FakeClient implements ToolAbortSignalSink {
+  private signal: AbortSignal | null = null;
+  setToolAbortSignal(signal: AbortSignal | null): void {
+    this.signal = signal;
+  }
+  getToolAbortSignal(): AbortSignal | null {
+    return this.signal;
+  }
+}
+
+// A ToolCallOptions with just the field the wrapper reads (abortSignal). The AI
+// SDK passes a fuller object; the wrapper only spreads it and reads abortSignal.
+const opts = (abortSignal?: AbortSignal): ToolCallOptions =>
+  ({ toolCallId: 't1', messages: [], abortSignal }) as unknown as ToolCallOptions;
+
+const tick = (ms = 5) => new Promise((r) => setTimeout(r, ms));
+
+describe('#487 wrapInAppToolWithCap — race-on-abort + safe-points', () => {
+  it('after Stop, no NEW simulated call starts (multi-call tool)', async () => {
+    const client = new FakeClient();
+    const started: number[] = [];
+    // A multi-call tool that mirrors paginateAll: it consults the client signal
+    // at a safe-point BEFORE starting each simulated network call.
+    const multiCall: Tool = {
+      execute: (async (_args: unknown) => {
+        for (let i = 0; i < 6; i++) {
+          // Safe-point: exactly what paginateAll / mutatePageContent do.
+          client.getToolAbortSignal()?.throwIfAborted();
+          started.push(i);
+          await tick(10);
+        }
+        return 'done';
+      }) as unknown as Tool['execute'],
+    } as Tool;
+
+    const wrapped = wrapInAppToolWithCap(multiCall, client, 10_000);
+    const ac = new AbortController();
+    const call = (
+      wrapped.execute as (a: unknown, o: ToolCallOptions) => Promise<unknown>
+    )({}, opts(ac.signal));
+
+    // Let one or two calls start, then Stop.
+    await tick(12);
+    ac.abort(new Error('user stop'));
+
+    await expect(call).rejects.toThrow(); // wrapper rejects promptly
+    const startedAtStop = started.length;
+
+    // Give the abandoned loser ample time; its next safe-point must throw because
+    // the (aborted) composite is still published on the client.
+    await tick(60);
+    expect(started.length).toBe(startedAtStop);
+    // It must NOT have run the whole sequence (that would mean Stop did nothing).
+    expect(started.length).toBeLessThan(6);
+  });
+
+  it('rejects immediately on Stop even if the call never settles (discard loser)', async () => {
+    const client = new FakeClient();
+    let settled = false;
+    const hang: Tool = {
+      execute: (async () => {
+        await new Promise(() => undefined); // never resolves
+        settled = true;
+      }) as unknown as Tool['execute'],
+    } as Tool;
+    const wrapped = wrapInAppToolWithCap(hang, client, 10_000);
+    const ac = new AbortController();
+    const call = (
+      wrapped.execute as (a: unknown, o: ToolCallOptions) => Promise<unknown>
+    )({}, opts(ac.signal));
+    await tick(5);
+    ac.abort();
+    await expect(call).rejects.toThrow();
+    expect(settled).toBe(false);
+  });
+
+  it('per-call cap rejects a hung call with no Stop signal', async () => {
+    const client = new FakeClient();
+    const hang: Tool = {
+      execute: (async () => {
+        await new Promise(() => undefined);
+      }) as unknown as Tool['execute'],
+    } as Tool;
+    // Tiny cap; no options.abortSignal at all (composite = cap only).
+    const wrapped = wrapInAppToolWithCap(hang, client, 20);
+    const start = Date.now();
+    await expect(
+      (wrapped.execute as (a: unknown, o: ToolCallOptions) => Promise<unknown>)(
+        {},
+        opts(undefined),
+      ),
+    ).rejects.toThrow(/per-call cap/);
+    expect(Date.now() - start).toBeLessThan(2000);
+  });
+
+  it('publishes a composite signal on the client for the duration of the call', async () => {
+    const client = new FakeClient();
+    let seenDuringCall: AbortSignal | null = null;
+    const probe: Tool = {
+      execute: (async () => {
+        seenDuringCall = client.getToolAbortSignal();
+        return 'ok';
+      }) as unknown as Tool['execute'],
+    } as Tool;
+    const wrapped = wrapInAppToolWithCap(probe, client, 10_000);
+    const ac = new AbortController();
+    await (
+      wrapped.execute as (a: unknown, o: ToolCallOptions) => Promise<unknown>
+    )({}, opts(ac.signal));
+    expect(seenDuringCall).not.toBeNull();
+    // The published composite must reflect the turn's Stop signal.
+    ac.abort();
+    expect((seenDuringCall as unknown as AbortSignal).aborted).toBe(true);
+  });
+
+  it('a completed call returns its raw result unchanged', async () => {
+    const client = new FakeClient();
+    const ok: Tool = {
+      execute: (async () => ({ items: [1, 2, 3] })) as unknown as Tool['execute'],
+    } as Tool;
+    const wrapped = wrapInAppToolWithCap(ok, client, 10_000);
+    const res = await (
+      wrapped.execute as (a: unknown, o: ToolCallOptions) => Promise<unknown>
+    )({}, opts(new AbortController().signal));
+    expect(res).toEqual({ items: [1, 2, 3] });
+  });
+
+  it('cap is env-tunable with a 2-minute default', () => {
+    const prev = process.env.AI_CHAT_INAPP_TOOL_CALL_CAP_MS;
+    delete process.env.AI_CHAT_INAPP_TOOL_CALL_CAP_MS;
+    expect(inAppToolCallCapMs()).toBe(120_000);
+    process.env.AI_CHAT_INAPP_TOOL_CALL_CAP_MS = '5000';
+    expect(inAppToolCallCapMs()).toBe(5000);
+    process.env.AI_CHAT_INAPP_TOOL_CALL_CAP_MS = 'not-a-number';
+    expect(inAppToolCallCapMs()).toBe(120_000);
+    if (prev === undefined) delete process.env.AI_CHAT_INAPP_TOOL_CALL_CAP_MS;
+    else process.env.AI_CHAT_INAPP_TOOL_CALL_CAP_MS = prev;
+  });
+});

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

@@ -23,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,
 });
 
 /**
@@ -275,6 +283,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
   const patchNodeCalls: unknown[][] = [];
   const insertNodeCalls: unknown[][] = [];
   const updatePageJsonCalls: unknown[][] = [];
+  const updatePageCalls: unknown[][] = [];
 
   const fakeClient: FakeDocmostClient = {
     patchNode: (...args: unknown[]) => {
@@ -289,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 = {
@@ -302,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;
@@ -340,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 () => {
@@ -370,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(
       {
@@ -381,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 () => {
@@ -437,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();
+  });
 });
 
 /**
@@ -847,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();
+  });
+});

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

@@ -1,5 +1,5 @@
 import { Injectable, Logger } from '@nestjs/common';
-import { tool, type Tool } from 'ai';
+import { tool, type Tool, type ToolCallOptions } from 'ai';
 import { z } from 'zod';
 import { User } from '@docmost/db/types/entity.types';
 import { TokenService } from '../../auth/services/token.service';
@@ -59,10 +59,12 @@ function __assertClientCallContract(client: DocmostClientLike): void {
   void client.getWorkspace();
   void client.getSpaces();
   void client.listPages(s, n, true);
+  void client.getTree(s, s, n);
+  void client.getPageContext(s);
   void client.listSidebarPages(s, s);
   void client.getOutline(s);
   void client.getPageJson(s);
-  void client.getNode(s, s);
+  void client.getNode(s, s, 'markdown');
   void client.searchInPage(s, s, {
     regex: true,
     caseSensitive: true,
@@ -84,12 +86,16 @@ function __assertClientCallContract(client: DocmostClientLike): void {
   void client.movePage(s, s, s);
   void client.deletePage(s);
   void client.editPageText(s, edits);
-  void client.patchNode(s, s, node);
-  void client.insertNode(s, node, {
-    position: 'append',
-    anchorNodeId: s,
-    anchorText: s,
-  });
+  void client.patchNode(s, s, { markdown: s, node });
+  void client.insertNode(
+    s,
+    { markdown: s, node },
+    {
+      position: 'append',
+      anchorNodeId: s,
+      anchorText: s,
+    },
+  );
   void client.deleteNode(s, s);
   void client.updatePageJson(s, node, s);
   void client.tableInsertRow(s, s, cells, n);
@@ -111,10 +117,29 @@ function __assertClientCallContract(client: DocmostClientLike): void {
     afterText: s,
   });
   void client.replaceImage(s, s, s, { align, alt: s });
-  // --- draw.io diagrams (#423) ---
+  // --- draw.io diagrams (#423 stage 1, #424 stage 2) ---
+  // The 5th `layout` arg (#424) is exercised so this parity assertion fails if the
+  // client signature drops it — it must reach the client from the shared execute.
   void client.drawioGet(s, s, 'xml');
-  void client.drawioCreate(s, { position: 'append', anchorNodeId: s }, s, s);
-  void client.drawioUpdate(s, s, s, s);
+  void client.drawioCreate(s, { position: 'append', anchorNodeId: s }, s, s, 'elk');
+  void client.drawioUpdate(s, s, s, s, 'elk');
+  // --- draw.io high-level semantic tools (#425 stage 3) ---
+  void client.drawioEditCells(s, s, [{ op: 'delete', cellId: s }], s);
+  void client.drawioFromGraph(
+    s,
+    { position: 'append', anchorNodeId: s },
+    { nodes: [{ id: s, label: s }] },
+    'LR',
+    s,
+    'full',
+    s,
+  );
+  void client.drawioFromMermaid(
+    s,
+    { position: 'append', anchorNodeId: s },
+    s,
+    s,
+  );
   // --- write (comment) ---
   void client.createComment(s, s, 'inline', s, s, s);
   void client.resolveComment(s, true);
@@ -134,6 +159,129 @@ function __assertClientCallContract(client: DocmostClientLike): void {
  * existing service-account `/mcp` path already calls loopback successfully, so
  * this works for single-workspace self-host.
  */
+/**
+ * #487: wall-clock cap for a SINGLE in-app tool call, env-tunable via
+ * `AI_CHAT_INAPP_TOOL_CALL_CAP_MS`. Bounds a read tool that would otherwise
+ * paginate for minutes and a content write whose collab commit hangs, and is the
+ * per-call CAP half of the composite abort signal every in-app tool is wrapped
+ * with (the other half is the turn's Stop signal). Default 2 minutes: generous
+ * for a legitimate long read/write, tight enough that a stuck call cannot pin the
+ * turn. The reconcile staleness floor (#487 commit 4) is derived as
+ * max(2 x this cap, 15 min), so keep this well under that.
+ */
+export function inAppToolCallCapMs(): number {
+  const raw = Number(process.env.AI_CHAT_INAPP_TOOL_CALL_CAP_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 120_000;
+}
+
+/** #487: the composite signal's reason as an Error (informative thrown value). */
+function inAppAbortReason(signal: AbortSignal): Error {
+  const r = signal.reason;
+  return r instanceof Error
+    ? r
+    : new Error(typeof r === 'string' ? r : 'In-app tool call aborted');
+}
+
+/**
+ * The client surface {@link wrapInAppToolWithCap} drives (#487). Both methods are
+ * OPTIONAL: the real loopback DocmostClient implements them (so a Stop/cap reaches
+ * its pagination / pre-commit safe-points), but a client that omits them still
+ * gets the OUTER guarantee — the race rejects on abort regardless. This keeps the
+ * wrapper decoupled from the exact client shape (unit-test doubles need not stub
+ * the plumbing).
+ */
+export interface ToolAbortSignalSink {
+  setToolAbortSignal?(signal: AbortSignal | null): void;
+  getToolAbortSignal?(): AbortSignal | null;
+}
+
+/**
+ * #487: wrap an in-app tool so a Stop (the turn's `options.abortSignal`) OR the
+ * per-call wall-clock cap REJECTS the call immediately, and so that SAME
+ * composite signal reaches the client's pagination / pre-commit safe-points (via
+ * `client.setToolAbortSignal`) — making a Stop stop the NEXT HTTP/WS call from
+ * starting.
+ *
+ * Reuses the RACE pattern of `wrapToolWithCallTimeout` (mcp-clients.service.ts):
+ * the call is raced against the composite signal, so on abort we reject in the
+ * SAME tick and DISCARD the loser promise. Its network / collab teardown latency
+ * therefore never blocks the turn — the supersede timeout W=10s (#487 commit 3)
+ * relies on this abort->settle latency being milliseconds, not a socket teardown.
+ * Awaiting the client's own signal-into-write path alone would NOT satisfy this
+ * (the loser could still be tearing down a collab socket).
+ *
+ * The composite is SET on the client at entry and deliberately NOT restored on
+ * unwind: after this wrapper rejects on abort, the ABANDONED loser promise keeps
+ * running, and its safe-points read the client field — leaving the (aborted)
+ * composite there is exactly what makes the loser's NEXT call throw and stop. The
+ * next in-app tool call overwrites the field with its own fresh composite before
+ * any of its safe-points run, so a stale settled signal never leaks forward.
+ * SINGLE-WRITER by phase-1 assumption — see DocmostClientContext.toolAbortSignal
+ * for the parallel-call caveat (#487).
+ *
+ * KNOWN LIMITATION (#487): a write tool that issues SEVERAL sequential collab
+ * commits can be aborted BETWEEN commits, leaving a partially-applied operation.
+ * Cancel guarantees "no NEW call starts", NOT "the write didn't land".
+ */
+export function wrapInAppToolWithCap(
+  toolDef: Tool,
+  client: ToolAbortSignalSink,
+  capMs: number,
+): Tool {
+  const original = toolDef.execute;
+  if (typeof original !== 'function') return toolDef;
+  const execute = async (args: unknown, options: ToolCallOptions) => {
+    const capController = new AbortController();
+    const timer = setTimeout(() => {
+      capController.abort(
+        new Error(`In-app tool call exceeded the ${capMs}ms per-call cap`),
+      );
+    }, capMs);
+    timer.unref?.();
+    const composite = options?.abortSignal
+      ? AbortSignal.any([options.abortSignal, capController.signal])
+      : capController.signal;
+    // Reject the MOMENT the composite fires, independent of whether `original`
+    // ever settles (a hung collab write / read would otherwise pin the turn). The
+    // losing `original` is left pending; Promise.race attaches a rejection
+    // handler to both inputs so a late rejection is never unhandled.
+    const aborted = new Promise<never>((_, reject) => {
+      const fail = () => reject(inAppAbortReason(composite));
+      if (composite.aborted) fail();
+      else composite.addEventListener('abort', fail, { once: true });
+    });
+    // Publish the composite so the client's pagination / pre-commit safe-points
+    // observe it (see the "not restored on unwind" rationale above). Guarded: a
+    // client without the plumbing still gets the OUTER race guarantee below.
+    client.setToolAbortSignal?.(composite);
+    try {
+      return await Promise.race([
+        (original as (a: unknown, o: ToolCallOptions) => Promise<unknown>)(
+          args,
+          { ...options, abortSignal: composite },
+        ),
+        aborted,
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  return { ...toolDef, execute } as unknown as Tool;
+}
+
+/** #487: apply {@link wrapInAppToolWithCap} to every tool in a set. */
+export function wrapInAppToolsWithCap(
+  tools: Record<string, Tool>,
+  client: ToolAbortSignalSink,
+  capMs: number,
+): Record<string, Tool> {
+  const out: Record<string, Tool> = {};
+  for (const [name, t] of Object.entries(tools)) {
+    out[name] = wrapInAppToolWithCap(t, client, capMs);
+  }
+  return out;
+}
+
 @Injectable()
 export class AiChatToolsService {
   private readonly logger = new Logger(AiChatToolsService.name);
@@ -161,7 +309,12 @@ export class AiChatToolsService {
     sessionId: string,
     workspaceId: string,
     aiChatId: string,
-  ): Promise<DocmostClientLike> {
+    // #487: the returned client also carries the tool-cancellation plumbing
+    // (setToolAbortSignal/getToolAbortSignal). These are host plumbing, NOT part
+    // of the tool-execute surface (DocmostClientMethod), so they are surfaced here
+    // as an intersection rather than by widening that Pick — keeping the
+    // positional-call drift-guard (#446) scoped to the actual tool methods.
+  ): Promise<DocmostClientLike & ToolAbortSignalSink> {
     const apiUrl =
       process.env.MCP_DOCMOST_API_URL ||
       `http://127.0.0.1:${process.env.PORT || 3000}/api`;
@@ -263,8 +416,19 @@ export class AiChatToolsService {
     // provenance tokens) and load the shared tool-spec registry. Client
     // construction is shared with the page-change detection path (#274) via
     // buildDocmostClient so both go over the exact same authenticated route.
-    const { sharedToolSpecs, createCommentSignalTracker } =
-      await loadDocmostMcp();
+    // searchShapes / getGuideSection (#424) are the PURE, no-network helpers
+    // backing drawioShapes / drawioGuide. They are `inlineBothHosts` specs (no
+    // canonical execute — their catalog loader uses import.meta and can't be
+    // value-imported into the zod-agnostic tool-specs.ts under the server's
+    // commonjs type-check), so the shared registry loop below SKIPS them and this
+    // service wires them inline (see drawioShapes/drawioGuide entries), mirroring
+    // how index.ts registers them on the standalone MCP host.
+    const {
+      sharedToolSpecs,
+      createCommentSignalTracker,
+      searchShapes,
+      getGuideSection,
+    } = await loadDocmostMcp();
     const client = await this.buildDocmostClient(
       user,
       sessionId,
@@ -294,10 +458,11 @@ export class AiChatToolsService {
 
     // The in-app toolset. It starts with the tools kept INLINE here for a
     // documented per-layer reason: an intentional behaviour/schema divergence from
-    // the standalone MCP surface (searchPages' hybrid RRF, updatePageContent's
-    // Markdown write, transformPage's guardrailed shorter schema), a
-    // snake_case/camelCase naming clash the shared registry forbids (getTable vs
-    // the MCP `table_get`), per-request state the registry loop cannot provide
+    // the standalone MCP surface (searchPages' hybrid RRF,
+    // transformPage's guardrailed shorter schema), a name clash the shared
+    // registry forbids (in-app `getTable` verb-first vs the MCP noun-first
+    // `tableGet` — the registry requires mcpName === inAppKey), per-request
+    // state the registry loop cannot provide
     // (getCurrentPage reads the resolved openedPage; searchPages closes over the
     // per-request user/embedding deps), or a tool with no MCP twin
     // (listSidebarPages/getComment/getPageHistory). Every SHARED tool is then added
@@ -438,28 +603,13 @@ export class AiChatToolsService {
       }),
 
       // --- WRITE tools (all reversible — history/trash; §6.5 / D3) ---
-
-      updatePageContent: tool({
-        description:
-          "Replace a page's body with new Markdown content (and optionally its " +
-          'title). Reversible: the previous version is kept in page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page to update.'),
-          content: z.string().describe('The new page body as Markdown.'),
-          title: z
-            .string()
-            .optional()
-            .describe('Optional new title for the page.'),
-        }),
-        execute: async ({ pageId, content, title }) => {
-          // updatePage mutates the live collab doc -> provenance flows from the
-          // collab-token provider. Returns { success, modified, message, pageId }.
-          const result = (await client.updatePage(pageId, content, title)) as {
-            success?: boolean;
-          };
-          return { pageId, updated: result?.success ?? true };
-        },
-      }),
+      //
+      // NOTE (issue #411): the plain-Markdown full-body-replace tool is no longer
+      // inline here — it moved to @docmost/mcp's SHARED_TOOL_SPECS as
+      // `updatePageMarkdown` (was inline `updatePageContent`) so it registers on
+      // BOTH the external MCP and the in-app agent. The registry loop below adds
+      // it under its inAppKey. importPageMarkdown stays a shared spec too (now
+      // inAppOnly — dropped from the external MCP surface, kept in-app).
 
       listSidebarPages: tool({
         description:
@@ -479,9 +629,9 @@ export class AiChatToolsService {
           await client.listSidebarPages(spaceId, pageId),
       }),
 
-      // NOT shared (kept inline): the MCP tool name `table_get` is noun-first
-      // while this key is `getTable` (verb-first), breaking the
-      // snake_case(inAppKey) convention the shared registry enforces. Its
+      // NOT shared (kept inline): the MCP tool name `tableGet` is noun-first
+      // while this key is `getTable` (verb-first), so it cannot satisfy the
+      // shared registry's `mcpName === inAppKey` convention (#412). Its
       // reference parameter is still named `table` (was `tableRef`) so it matches
       // the migrated table row/cell tools below.
       getTable: tool({
@@ -524,7 +674,7 @@ export class AiChatToolsService {
 
       // INTENTIONAL per-transport divergence (not shared): deliberately omits the
       // `deleteComments` schema field (comment-deletion guardrail) and carries a
-      // much shorter description; the standalone MCP `docmost_transform` exposes
+      // much shorter description; the standalone MCP `docmostTransform` exposes
       // the full helper catalogue. Different schema, so kept per-layer.
       transformPage: tool({
         description:
@@ -555,6 +705,8 @@ export class AiChatToolsService {
     // WHICH mapping to run and returns its value directly (no envelope). For each
     // spec:
     //   - skip `mcpOnly` specs (they belong to the standalone MCP host only);
+    //   - skip `inlineBothHosts` specs (drawioShapes / drawioGuide): they carry
+    //     no execute and are wired INLINE just below, calling the pure helpers;
     //   - use `inAppExecute` when the spec declares a DELIBERATE per-layer
     //     difference (a projected result shape, a different guardrail message);
     //   - otherwise use the canonical `execute` (raw client result, identical to
@@ -564,6 +716,7 @@ export class AiChatToolsService {
     // arg mapping lives — it can no longer silently drift from the MCP host.
     for (const spec of Object.values(sharedToolSpecs)) {
       if (spec.mcpOnly) continue;
+      if (spec.inlineBothHosts) continue;
       const run = spec.inAppExecute ?? spec.execute;
       if (!run) continue; // defensive: a shared spec always carries one of them.
       tools[spec.inAppKey] = sharedTool(
@@ -573,6 +726,25 @@ export class AiChatToolsService {
       );
     }
 
+    // drawioShapes / drawioGuide (#424): `inlineBothHosts` registry specs wired
+    // here with the SAME schema+description the shared spec pins, but calling the
+    // pure searchShapes / getGuideSection helpers off the loaded @docmost/mcp
+    // module — they are not client methods and their catalog loader uses
+    // import.meta, so they cannot live in the zod-agnostic shared execute. The raw
+    // result is identical to the MCP host's (which wraps it as JSON text); here
+    // the in-app host returns it plain, exactly like every other shared tool.
+    tools[sharedToolSpecs.drawioShapes.inAppKey] = sharedTool(
+      sharedToolSpecs.drawioShapes,
+      async ({ query, category, limit }) => {
+        const results = searchShapes(query, { category, limit });
+        return { query, count: results.length, results };
+      },
+    );
+    tools[sharedToolSpecs.drawioGuide.inAppKey] = sharedTool(
+      sharedToolSpecs.drawioGuide,
+      async ({ section }) => getGuideSection(section),
+    );
+
     // Passive "new comments: N" signal (#417). PER-TURN state (forUser runs once
     // per turn), so the watermark starts now and only comments a human leaves
     // WHILE this turn runs are signalled — exactly the mid-turn loop; between-turn
@@ -586,7 +758,15 @@ export class AiChatToolsService {
     // dependency and reuses the CASL enforcement already on `client`. When the
     // loaded package predates #417 (factory undefined) or the loader is mocked in
     // a unit test, signalling is a pure no-op and results are byte-identical.
-    if (!createCommentSignalTracker) return tools;
+    // #487: wrap every in-app tool with the race-on-abort + per-call cap guard so
+    // a Stop / cap rejects immediately AND reaches the client's write/pagination
+    // safe-points. Applied as the OUTERMOST wrapper (over the comment-signal
+    // wrapper below) so the race governs the whole call. The client carries the
+    // per-call composite signal via setToolAbortSignal.
+    const capMs = inAppToolCallCapMs();
+    if (!createCommentSignalTracker) {
+      return wrapInAppToolsWithCap(tools, client, capMs);
+    }
 
     const tracker = createCommentSignalTracker({
       probe: async (pageId: string, sinceMs: number) => {
@@ -615,7 +795,11 @@ export class AiChatToolsService {
       },
     });
 
-    return wrapToolsWithCommentSignal(tools, tracker);
+    return wrapInAppToolsWithCap(
+      wrapToolsWithCommentSignal(tools, tracker),
+      client,
+      capMs,
+    );
   }
 }
 

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

@@ -283,10 +283,18 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
       DocmostClient: function () {
         return fakeClient as DocmostClientLike;
       } as unknown as loader.DocmostClientCtor,
-      sharedToolSpecs: SHARED_TOOL_SPECS as Record<string, loader.SharedToolSpec>,
+      sharedToolSpecs: SHARED_TOOL_SPECS as unknown as Record<string, loader.SharedToolSpec>,
       // Wire the REAL factory so the in-app path is exercised end to end.
       createCommentSignalTracker:
         createCommentSignalTracker as unknown as loader.CommentSignalTrackerFactory,
+      // Pure no-network draw.io helpers (#424) — required on the loader return;
+      // this comment-signal test doesn't exercise them, so no-op stubs suffice.
+      searchShapes: (() => []) as unknown as loader.SearchShapesFn,
+      getGuideSection: (() => ({
+        section: '',
+        content: '',
+        sections: [],
+      })) as unknown as loader.GetGuideSectionFn,
     });
     return new AiChatToolsService(
       tokenServiceStub as never,

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

@@ -1,7 +1,15 @@
 import { createHash } from 'node:crypto';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  readdirSync,
+  statSync,
+  readFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 
 import { computeSrcRegistryStamp } from './docmost-client.loader';
 
@@ -30,10 +38,14 @@ function assertStaleGuard(
   }
 }
 
-// Build a throwaway `<pkg>/build/index.js` + optional `<pkg>/src/tool-specs.ts`
-// layout so `computeSrcRegistryStamp(<pkg>/build/index.js)` resolves src the same
-// way the loader does (dirname(dirname(entry))/src/tool-specs.ts).
-function makeFakePackage(toolSpecsSource: string | null): {
+// Build a throwaway `<pkg>/build/index.js` + optional `<pkg>/src/` tree so
+// `computeSrcRegistryStamp(<pkg>/build/index.js)` resolves src the same way the
+// loader does (dirname(dirname(entry))/src). Since #486 the stamp hashes the WHOLE
+// src tree, so a fixture is a { relPath: content } map. A bare string is sugar for
+// a single `tool-specs.ts`; `null` means "no src tree" (the prod no-op path).
+function makeFakePackage(
+  src: string | Record<string, string> | null,
+): {
   entry: string;
   cleanup: () => void;
 } {
@@ -42,10 +54,15 @@ function makeFakePackage(toolSpecsSource: string | null): {
   mkdirSync(buildDir, { recursive: true });
   const entry = join(buildDir, 'index.js');
   writeFileSync(entry, '// fake @docmost/mcp build entry\n', 'utf8');
-  if (toolSpecsSource !== null) {
+  if (src !== null) {
+    const files =
+      typeof src === 'string' ? { 'tool-specs.ts': src } : src;
     const srcDir = join(root, 'src');
-    mkdirSync(srcDir, { recursive: true });
-    writeFileSync(join(srcDir, 'tool-specs.ts'), toolSpecsSource, 'utf8');
+    for (const [rel, content] of Object.entries(files)) {
+      const full = join(srcDir, rel);
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, content, 'utf8');
+    }
   }
   return { entry, cleanup: () => rmSync(root, { recursive: true, force: true }) };
 }
@@ -93,34 +110,109 @@ describe('computeSrcRegistryStamp (#447 stale-build guard)', () => {
     }
   });
 
-  // CROSS-IMPL EQUALITY (covers reviewer suggestion 2). The SAME fixed input and
+  // #486 CORE (negative): an edit to a NON-tool-specs src file (client.ts) with a
+  // rebuild NOT run must move the src stamp away from the built REGISTRY_STAMP, so
+  // the loader's stale-check refuses. Under the old tool-specs.ts-only hash this
+  // edit was invisible and a stale build/ served the old client.ts silently.
+  it('a client.ts edit (no rebuild) moves the src stamp -> loader refuses (#486)', () => {
+    // "Built" state: the package as it was compiled.
+    const built = makeFakePackage({
+      'tool-specs.ts': 'export const SPECS = 1;\n',
+      'client.ts': "export const impl = 'v1';\n",
+    });
+    // "Dev edited src, forgot to rebuild": client.ts changed, tool-specs.ts not.
+    const edited = makeFakePackage({
+      'tool-specs.ts': 'export const SPECS = 1;\n',
+      'client.ts': "export const impl = 'v2';\n",
+    });
+    try {
+      const builtStamp = computeSrcRegistryStamp(built.entry);
+      const editedStamp = computeSrcRegistryStamp(edited.entry);
+      expect(builtStamp).not.toBeNull();
+      expect(editedStamp).not.toBe(builtStamp);
+      // build/ still carries builtStamp; src now hashes to editedStamp -> refuse.
+      expect(() => assertStaleGuard(editedStamp, builtStamp as string)).toThrow(
+        STALE_BUILD_MESSAGE,
+      );
+    } finally {
+      built.cleanup();
+      edited.cleanup();
+    }
+  });
+
+  // *.generated.ts is excluded (the codegen's own output — a fixed-point cycle
+  // otherwise): its presence/content must not move the stamp.
+  it('excludes *.generated.ts from the stamp', () => {
+    const without = makeFakePackage({ 'tool-specs.ts': 'x\n' });
+    const withGen = makeFakePackage({
+      'tool-specs.ts': 'x\n',
+      'registry-stamp.generated.ts': 'export const REGISTRY_STAMP = "abc";\n',
+    });
+    try {
+      expect(computeSrcRegistryStamp(withGen.entry)).toBe(
+        computeSrcRegistryStamp(without.entry),
+      );
+    } finally {
+      without.cleanup();
+      withGen.cleanup();
+    }
+  });
+
+  // CROSS-IMPL EQUALITY (covers reviewer suggestion 2). The SAME fixed tree and
   // EXPECTED hash are asserted in the mcp-side node test
   // (packages/mcp/test/unit/registry-stamp.test.mjs) against the codegen's
   // `computeRegistryStamp`. Asserting the SAME pair here against the loader's
-  // `computeSrcRegistryStamp` proves both implementations normalize+hash
+  // `computeSrcRegistryStamp` proves both implementations enumerate+normalize+hash
   // identically; a divergence in EITHER side reddens one of the two tests.
-  it('matches the documented cross-impl hash for a fixed input', () => {
-    const FIXED_INPUT = 'line1\r\nline2\n';
-    const EXPECTED =
-      '683376e290829b482c2655745caffa7a1dccfa10afaa62dac2b42dd6c68d0f83';
-    const { entry, cleanup } = makeFakePackage(FIXED_INPUT);
+  const CROSS_IMPL_TREE = {
+    'tool-specs.ts': 'line1\r\nline2\n',
+    'client/read.ts': 'export const R = 1;\n',
+    'registry-stamp.generated.ts': 'export const REGISTRY_STAMP="ignored";\n',
+  };
+  const CROSS_IMPL_EXPECTED =
+    '131c1b9e4e2f5a7d6cef91ca8df619822b442f52bc45ebd09474a4c1d6728616';
+
+  it('matches the documented cross-impl hash for a fixed tree', () => {
+    const { entry, cleanup } = makeFakePackage(CROSS_IMPL_TREE);
     try {
-      expect(computeSrcRegistryStamp(entry)).toBe(EXPECTED);
+      expect(computeSrcRegistryStamp(entry)).toBe(CROSS_IMPL_EXPECTED);
     } finally {
       cleanup();
     }
   });
 
-  it('the documented EXPECTED is the normalize+sha256 of the fixed input', () => {
-    // Proves EXPECTED is not a magic constant but the documented computation.
-    const FIXED_INPUT = 'line1\r\nline2\n';
-    const normalized = FIXED_INPUT.replace(/\r\n/g, '\n').replace(/\n$/, '');
-    const expected = createHash('sha256')
-      .update(normalized, 'utf8')
-      .digest('hex');
-    const { entry, cleanup } = makeFakePackage(FIXED_INPUT);
+  it('the documented EXPECTED is the enumerate+normalize+sha256 of the tree', () => {
+    // Proves EXPECTED is not a magic constant but the documented computation — a
+    // local re-implementation of the loader's tree walk.
+    const { entry, cleanup } = makeFakePackage(CROSS_IMPL_TREE);
     try {
-      expect(computeSrcRegistryStamp(entry)).toBe(expected);
+      const srcDir = join(dirname(dirname(entry)), 'src');
+      const collect = (dir: string): string[] => {
+        const out: string[] = [];
+        for (const e of readdirSync(dir)) {
+          const f = join(dir, e);
+          if (statSync(f).isDirectory()) out.push(...collect(f));
+          else if (e.endsWith('.ts') && !e.endsWith('.generated.ts'))
+            out.push(f);
+        }
+        return out;
+      };
+      const files = collect(srcDir)
+        .map((abs) => ({ rel: relative(srcDir, abs).split(sep).join('/'), abs }))
+        .sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+      const h = createHash('sha256');
+      for (const { rel, abs } of files) {
+        const n = readFileSync(abs, 'utf8')
+          .replace(/\r\n/g, '\n')
+          .replace(/\n$/, '');
+        h.update(rel, 'utf8');
+        h.update('\0', 'utf8');
+        h.update(n, 'utf8');
+        h.update('\0', 'utf8');
+      }
+      const localHash = h.digest('hex');
+      expect(computeSrcRegistryStamp(entry)).toBe(localHash);
+      expect(localHash).toBe(CROSS_IMPL_EXPECTED);
     } finally {
       cleanup();
     }

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

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import type { DocmostClient, SharedToolSpec } from '@docmost/mcp';
 
@@ -23,6 +23,8 @@ type DocmostClientMethod =
   | 'getWorkspace'
   | 'getSpaces'
   | 'listPages'
+  | 'getTree'
+  | 'getPageContext'
   | 'listSidebarPages'
   | 'getOutline'
   | 'getPageJson'
@@ -62,10 +64,17 @@ type DocmostClientMethod =
   | 'insertImage'
   | 'replaceImage'
   | 'insertFootnote'
-  // --- draw.io diagrams (#423, stage 1) ---
+  // --- draw.io diagrams (#423 stage 1, #424 stage 2) ---
+  // DERIVED from the real DocmostClient (#446): drawioCreate/drawioUpdate carry
+  // the optional layout:"elk" 5th arg in the real signature, so the layout parity
+  // (#440) is inherited automatically — no hand-written mirror to keep in sync.
   | 'drawioGet'
   | 'drawioCreate'
   | 'drawioUpdate'
+  // --- draw.io high-level semantic tools (#425 stage 3) ---
+  | 'drawioEditCells'
+  | 'drawioFromGraph'
+  | 'drawioFromMermaid'
   // --- write (comment) ---
   | 'createComment'
   | 'resolveComment';
@@ -141,6 +150,19 @@ export type CommentSignalTrackerFactory = (options: {
   debounceMs?: number;
 }) => CommentSignalTrackerLike;
 
+// Pure, no-network draw.io helpers (#424). These are plain functions on the
+// module (NOT DocmostClient methods) — the in-app AI-SDK service calls them
+// directly to wire drawioShapes / drawioGuide, mirroring the MCP server.
+export type SearchShapesFn = (
+  query: string,
+  opts?: { category?: string; limit?: number },
+) => Array<Record<string, unknown>>;
+export type GetGuideSectionFn = (section?: string) => {
+  section: string;
+  content: string;
+  sections: string[];
+};
+
 interface DocmostMcpModule {
   DocmostClient: DocmostClientCtor;
   SHARED_TOOL_SPECS: Record<string, SharedToolSpec>;
@@ -153,6 +175,15 @@ interface DocmostMcpModule {
   // the mocked loader in unit tests) — the stale-check below is a NO-OP when it
   // is missing, so an older build never wrongly fails startup.
   REGISTRY_STAMP?: string;
+  // Pure, no-network draw.io helpers (#424) backing drawioShapes / drawioGuide.
+  // Those two specs are `inlineBothHosts` (they stay in SHARED_TOOL_SPECS for the
+  // shared contract but carry no execute — their catalog loader uses import.meta
+  // and can't be value-imported into the zod-agnostic tool-specs.ts), so the
+  // in-app service wires them INLINE off these helpers, mirroring the standalone
+  // MCP host. Exposed off the loaded module so the service and its test mocks can
+  // reach them.
+  searchShapes: SearchShapesFn;
+  getGuideSection: GetGuideSectionFn;
 }
 
 /**
@@ -160,33 +191,52 @@ interface DocmostMcpModule {
  * present. Returns the stamp string, or `null` when the source is absent (a prod
  * image ships only build/, no src/). MUST stay byte-for-byte identical to
  * packages/mcp/scripts/gen-registry-stamp.mjs's `computeRegistryStamp` so the
- * build-time and src-time hashes agree: same input file (src/tool-specs.ts), same
- * normalization (CRLF -> LF, strip a single trailing newline), same sha256.
+ * build-time and src-time hashes agree: same file set (every src/**\/*.ts except
+ * *.generated.ts), same POSIX-relative sort, same per-file normalization (CRLF ->
+ * LF, strip a single trailing newline) with the same path+content framing, same
+ * sha256. Hashing the WHOLE src tree (not just tool-specs.ts) is #486: an edit to
+ * client.ts / a client/* module / comment-signal / drawio-* without a rebuild
+ * must also be caught, otherwise build/ silently serves the old code.
  *
  * DEV vs PROD detection is by FILE EXISTENCE, not NODE_ENV: we resolve the
  * package's own directory from `require.resolve('@docmost/mcp')` (which points at
- * build/index.js) and look for ../src/tool-specs.ts next to it. In a dev/test
- * worktree that file exists; in a prod image (build/ only, src/ stripped) it does
- * not, so this returns null and the caller skips the check. Any error (ENOENT, a
- * bad resolve) is swallowed to null — the stale-check must NEVER break startup.
+ * build/index.js) and look for ../src next to it. In a dev/test worktree that
+ * directory exists; in a prod image (build/ only, src/ stripped) it does not, so
+ * this returns null and the caller skips the check. Any error (ENOENT, a bad
+ * resolve) is swallowed to null — the stale-check must NEVER break startup.
  *
  * Exported for unit testing (docmost-client.loader.spec.ts): the export keyword
  * is behaviourally a no-op — the module-internal caller `loadDocmostMcp` is
  * unaffected. The test drives the null (no-src) path and asserts this
- * normalize+sha256 stays identical to the codegen's `computeRegistryStamp`.
+ * enumerate+normalize+sha256 stays identical to the codegen's
+ * `computeRegistryStamp`.
  */
 export function computeSrcRegistryStamp(packageEntry: string): string | null {
   try {
     // packageEntry is <pkg>/build/index.js; the source lives at <pkg>/src/.
-    const toolSpecsPath = join(
-      dirname(dirname(packageEntry)),
-      'src',
-      'tool-specs.ts',
-    );
-    if (!existsSync(toolSpecsPath)) return null; // prod: no src tree -> skip.
-    const source = readFileSync(toolSpecsPath, 'utf8');
-    const normalized = source.replace(/\r\n/g, '\n').replace(/\n$/, '');
-    return createHash('sha256').update(normalized, 'utf8').digest('hex');
+    const srcDir = join(dirname(dirname(packageEntry)), 'src');
+    if (!existsSync(srcDir)) return null; // prod: no src tree -> skip.
+    // Enumerate every src/**\/*.ts except the codegen's own *.generated.ts
+    // output (including it would be a fixed-point cycle). Sort by POSIX-relative
+    // path so ordering is platform-independent, then fold each file's relative
+    // path + normalized content into one hash — identical to the codegen.
+    const files = collectStampFiles(srcDir)
+      .map((abs) => ({
+        rel: relative(srcDir, abs).split(sep).join('/'),
+        abs,
+      }))
+      .sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+    const hash = createHash('sha256');
+    for (const { rel, abs } of files) {
+      const normalized = readFileSync(abs, 'utf8')
+        .replace(/\r\n/g, '\n')
+        .replace(/\n$/, '');
+      hash.update(rel, 'utf8');
+      hash.update('\0', 'utf8');
+      hash.update(normalized, 'utf8');
+      hash.update('\0', 'utf8');
+    }
+    return hash.digest('hex');
   } catch {
     // Never let a resolution/read hiccup break server startup — treat as "no
     // src available" and skip the check (identical to the prod no-op path).
@@ -194,6 +244,24 @@ export function computeSrcRegistryStamp(packageEntry: string): string | null {
   }
 }
 
+/**
+ * Recursively enumerate every `*.ts` under `dir`, EXCLUDING `*.generated.ts`.
+ * Mirror of the codegen's `collectStampFiles` (packages/mcp/scripts/
+ * gen-registry-stamp.mjs) — keep the two walk/filter rules identical.
+ */
+function collectStampFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      out.push(...collectStampFiles(full));
+    } else if (entry.endsWith('.ts') && !entry.endsWith('.generated.ts')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
 // TS with module:commonjs downlevels a literal `import()` to `require()`, which
 // cannot load the ESM-only `@docmost/mcp` package. Indirect through Function so
 // the real dynamic `import()` survives compilation and can load ESM from
@@ -216,6 +284,8 @@ export async function loadDocmostMcp(): Promise<{
   DocmostClient: DocmostClientCtor;
   sharedToolSpecs: Record<string, SharedToolSpec>;
   createCommentSignalTracker?: CommentSignalTrackerFactory;
+  searchShapes: SearchShapesFn;
+  getGuideSection: GetGuideSectionFn;
 }> {
   if (!modulePromise) {
     modulePromise = (async () => {
@@ -261,5 +331,8 @@ export async function loadDocmostMcp(): Promise<{
     // Optional: forwarded when present so the in-app layer can build the passive
     // comment signal (#417); undefined on a stale build => signal disabled.
     createCommentSignalTracker: mod.createCommentSignalTracker,
+    // Pure no-network draw.io helpers (#424); not client methods.
+    searchShapes: mod.searchShapes,
+    getGuideSection: mod.getGuideSection,
   };
 }

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

@@ -224,7 +224,7 @@ describe('PublicShareChatToolsService.forShare', () => {
         (tools.getSharePage as unknown as ToolExec).execute({
           pageId: 'page-1',
         }),
-      ).rejects.toThrow('That page is not part of this published share.');
+      ).rejects.toThrow('The requested page is not available in this share.');
 
       // No content is ever fetched/returned for a non-resolving page.
       expect(shareService.updatePublicAttachments).not.toHaveBeenCalled();

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

@@ -7,6 +7,22 @@ import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { jsonToMarkdown } from '../../../collaboration/collaboration.util';
 import { modelFriendlyInput } from './model-friendly-input';
 
+/**
+ * A tool error whose message is DELIBERATELY safe to expose to an anonymous
+ * share reader (and to the model, for self-correction). Every OTHER thrown error
+ * is treated as internal and replaced with a generic string by `wrapToolErrors`,
+ * so a raw exception message — an internal page title, a DB/stack fragment, a
+ * driver detail — never rides the public UI stream (#394).
+ */
+export class ShareToolError extends Error {}
+
+// The only two classified strings an anonymous reader may ever see from a tool
+// failure. The specific one keeps the model's self-correction useful ("try a
+// different page"); the generic one reveals nothing about the internal fault.
+const SHARE_TOOL_ERROR_NOT_AVAILABLE =
+  'The requested page is not available in this share.';
+const SHARE_TOOL_ERROR_GENERIC = 'The tool could not complete the request.';
+
 /**
  * Isolated, READ-ONLY toolset for the ANONYMOUS public-share assistant.
  *
@@ -44,7 +60,7 @@ export class PublicShareChatToolsService {
    * are NO write tools, NO comments/history, NO cross-space or external tools.
    */
   forShare(shareId: string, workspaceId: string): Record<string, Tool> {
-    return {
+    return this.wrapToolErrors({
       searchSharePages: tool({
         description:
           'Search the pages of THIS published documentation share for a ' +
@@ -96,7 +112,7 @@ export class PublicShareChatToolsService {
         execute: async ({ pageId }) => {
           const id = (pageId ?? '').trim();
           if (!id) {
-            throw new Error('A pageId is required.');
+            throw new ShareToolError('A pageId is required.');
           }
           // Resolve via the SINGLE canonical share-access boundary: confirms the
           // page resolves to THIS share (recursive CTE up the tree, honouring
@@ -112,7 +128,7 @@ export class PublicShareChatToolsService {
             workspaceId,
           );
           if (!resolved) {
-            throw new Error('That page is not part of this published share.');
+            throw new ShareToolError(SHARE_TOOL_ERROR_NOT_AVAILABLE);
           }
           const { page } = resolved;
 
@@ -193,6 +209,57 @@ export class PublicShareChatToolsService {
           }
         },
       }),
-    };
+    });
+  }
+
+  /**
+   * Wrap every tool's `execute` so a THROWN error is sanitized in ONE place —
+   * closing the byte leak, the render, and the model context at once (#394).
+   *
+   * The AI SDK surfaces a tool-execution throw as an atomic `tool-output-error`
+   * frame on the v6 UI stream whose `errorText` is the thrown message; on the
+   * public share that frame goes straight to an anonymous reader. Unwrapped, a
+   * raw exception (an internal page title, a DB/stack fragment, a driver detail)
+   * would ride that frame verbatim. Here we catch it, LOG the full detail
+   * server-side only, and re-throw a CLASSIFIED, safe error: the tool's own
+   * intentional ShareToolError messages pass through (they keep the model's
+   * self-correction useful), everything else collapses to a generic string.
+   */
+  private wrapToolErrors(
+    tools: Record<string, Tool>,
+  ): Record<string, Tool> {
+    const wrapped: Record<string, Tool> = {};
+    for (const [name, t] of Object.entries(tools)) {
+      const original = t.execute;
+      if (typeof original !== 'function') {
+        wrapped[name] = t;
+        continue;
+      }
+      wrapped[name] = {
+        ...t,
+        execute: async (args: unknown, options: unknown) => {
+          try {
+            return await (
+              original as (a: unknown, o: unknown) => Promise<unknown>
+            )(args, options);
+          } catch (err) {
+            const safe =
+              err instanceof ShareToolError
+                ? err.message
+                : SHARE_TOOL_ERROR_GENERIC;
+            // Full detail to the server log ONLY — never to the anon.
+            this.logger.warn(
+              `Public share tool "${name}" failed: ${
+                err instanceof Error ? err.message : String(err)
+              }`,
+            );
+            // This safe string is ALL that rides the tool-output-error frame,
+            // becomes model context, and could be rendered — one choke point.
+            throw new ShareToolError(safe);
+          }
+        },
+      } as Tool;
+    }
+    return wrapped;
   }
 }

apps/server/src/core/ai-chat/tools/shared-tool-specs.contract.spec.ts

@@ -17,8 +17,10 @@ import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs
  * This test fails the build if a spec is added to the registry but never wired
  * in-app, if an `inAppKey` is renamed without updating the service, if the
  * description drifts between the registry and the exposed tool, if the
- * snake_case `mcpName` <-> camelCase `inAppKey` convention is broken, or if the
- * exposed tool's input-schema keys diverge from the spec's `buildShape`.
+ * `mcpName === inAppKey` convention is broken (issue #412 unified the external
+ * MCP tool name with the in-app key — both are the same camelCase identifier),
+ * or if the exposed tool's input-schema keys diverge from the spec's
+ * `buildShape`.
  *
  * It does NOT need @docmost/mcp built: the registry is imported from TS source,
  * and the ESM loader is mocked so `forUser()` never dynamically imports the
@@ -45,6 +47,16 @@ describe('SHARED_TOOL_SPECS contract parity', () => {
         string,
         loader.SharedToolSpec
       >,
+      // Pure no-network draw.io helpers (#424). The contract test never executes
+      // a tool body, so type-correct stubs suffice (the real functions can't be
+      // imported here — drawio-shapes.ts uses import.meta, incompatible with the
+      // CommonJS jest transform).
+      searchShapes: (() => []) as unknown as loader.SearchShapesFn,
+      getGuideSection: (() => ({
+        section: 'index',
+        content: '',
+        sections: [],
+      })) as unknown as loader.GetGuideSectionFn,
     });
     const service = new AiChatToolsService(
       tokenServiceStub as never,
@@ -64,13 +76,9 @@ describe('SHARED_TOOL_SPECS contract parity', () => {
 
   afterAll(() => jest.restoreAllMocks());
 
-  // camelCase -> snake_case, matching the registry's mcpName convention.
-  const toSnake = (s: string) =>
-    s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
-
   // Type as the (optional-buildShape) SharedToolSpec; the `satisfies` literal
   // above otherwise narrows to a union where some members lack buildShape.
-  const specEntries = Object.entries(SHARED_TOOL_SPECS) as Array<
+  const specEntries = Object.entries(SHARED_TOOL_SPECS) as unknown as Array<
     [string, loader.SharedToolSpec]
   >;
 
@@ -86,8 +94,8 @@ describe('SHARED_TOOL_SPECS contract parity', () => {
       expect(spec.inAppKey).toBe(registryKey);
     });
 
-    it('mcpName is the snake_case form of inAppKey', () => {
-      expect(spec.mcpName).toBe(toSnake(spec.inAppKey));
+    it('mcpName equals inAppKey (unified camelCase name, #412)', () => {
+      expect(spec.mcpName).toBe(spec.inAppKey);
     });
 
     it('is exposed in-app under its inAppKey', () => {

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

@@ -27,16 +27,18 @@ import type { DocmostClientLike } from './docmost-client.loader';
  */
 
 describe('tool tier metadata (#332)', () => {
-  it('core set is the documented 13 + searchInPage + insertFootnote (15)', () => {
-    expect(CORE_TOOL_KEYS).toHaveLength(15);
+  it('core set is the documented 13 + searchInPage + insertFootnote + getTree + getPageContext (17, #443)', () => {
+    expect(CORE_TOOL_KEYS).toHaveLength(17);
     expect(CORE_TOOL_SET.has('searchInPage')).toBe(true); // #330, promoted to core
     expect(CORE_TOOL_SET.has('insertFootnote')).toBe(true); // #410, promoted to core
+    expect(CORE_TOOL_SET.has('getTree')).toBe(true); // #443, promoted to core
+    expect(CORE_TOOL_SET.has('getPageContext')).toBe(true); // #443, promoted to core
     // loadTools is a meta-tool, not a normal core key.
     expect(CORE_TOOL_SET.has(LOAD_TOOLS_NAME)).toBe(false);
   });
 
   it('#410 image tools are DEFERRED, footnote tool is CORE', () => {
-    // insert_footnote is core (symmetric with editPageText); the image tools stay
+    // insertFootnote is core (symmetric with editPageText); the image tools stay
     // deferred (rare, fat — loaded on demand). Assert both the spec tier and the
     // CORE_TOOL_SET membership so a future tier edit that desyncs them fails here.
     expect(SHARED_TOOL_SPECS.insertFootnote.tier).toBe('core');
@@ -123,7 +125,14 @@ describe('deferred catalog ↔ live forUser() toolset partition (#332, F3)', ()
       DocmostClient: function () {
         return {} as DocmostClientLike;
       } as unknown as loader.DocmostClientCtor,
-      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); tool bodies are never executed here.
+      searchShapes: (() => []) as unknown as loader.SearchShapesFn,
+      getGuideSection: (() => ({
+        section: 'index',
+        content: '',
+        sections: [],
+      })) as unknown as loader.GetGuideSectionFn,
     });
     const service = new AiChatToolsService(
       {
@@ -232,6 +241,16 @@ describe('applyLoadTools (#332)', () => {
     expect(LOAD_TOOLS_DESCRIPTION).toContain('only ACTIVATES them');
     expect(LOAD_TOOLS_DESCRIPTION).toContain('callable on your NEXT step');
   });
+
+  it('loadTools description tells the model CORE tools are always active (#444)', () => {
+    expect(LOAD_TOOLS_DESCRIPTION).toContain(
+      'Tools NOT listed in the catalog are CORE and ALWAYS active',
+    );
+    expect(LOAD_TOOLS_DESCRIPTION).toContain('NEVER via loadTools');
+    // Names it out explicitly so the model doesn't loadTools a core tool.
+    expect(LOAD_TOOLS_DESCRIPTION).toContain('createComment');
+    expect(LOAD_TOOLS_DESCRIPTION).toContain('searchInPage');
+  });
 });
 
 describe('editorial "Corrector" scenario is fully served by CORE (#332)', () => {

apps/server/src/core/ai-chat/tools/tool-tiers.ts

@@ -39,12 +39,14 @@ export interface ToolCatalogEntry {
 
 /**
  * CORE (always-active) in-app tool keys — 13 frequent/tiny tools + `searchInPage`
- * (#330) + `insertFootnote` (#410). `searchInPage` is core because it is frequent
- * for the editorial roles this feature targets; `insertFootnote` is core so the
- * footnote tool is NOT hidden while its natural sibling `editPageText` is always
- * active (that asymmetry is exactly what pushed the agent to write literal
- * `^[...]`). `loadTools` is active too but is not a normal tool key (it is added
- * to activeTools separately).
+ * (#330) + `insertFootnote` (#410) + `getTree`/`getPageContext` (#443).
+ * `searchInPage` is core because it is frequent for the editorial roles this
+ * feature targets; `insertFootnote` is core so the footnote tool is NOT hidden
+ * while its natural sibling `editPageText` is always active (that asymmetry is
+ * exactly what pushed the agent to write literal `^[...]`). `getTree` and
+ * `getPageContext` are the single-call navigation/lookup tools — core so the
+ * agent never has to loadTools just to orient itself. `loadTools` is active too
+ * but is not a normal tool key (it is added to activeTools separately).
  */
 export const CORE_TOOL_KEYS = [
   'searchPages',
@@ -60,12 +62,17 @@ export const CORE_TOOL_KEYS = [
   'listComments',
   'resolveComment',
   'editPageText',
-  // #330 search_in_page — frequent for editorial sweeps; core despite predating
+  // #330 searchInPage — frequent for editorial sweeps; core despite predating
   // the issue's tier list.
   'searchInPage',
-  // #410 insert_footnote — core so pinpoint citations to already-written text
+  // #410 insertFootnote — core so pinpoint citations to already-written text
   // don't degrade into literal `^[...]`; kept symmetric with editPageText.
   'insertFootnote',
+  // #443 getTree + getPageContext — cheap single-call navigation/lookup tools
+  // (the core listPages even points to getTree); core so the agent never has
+  // to loadTools just to orient itself.
+  'getTree',
+  'getPageContext',
 ] as const;
 
 /** O(1) membership test for the core tier. */
@@ -84,7 +91,10 @@ export const LOAD_TOOLS_DESCRIPTION =
   'block in your instructions. Pass the EXACT tool names from the catalog; this\n' +
   'call only ACTIVATES them and returns { loaded: [...] } — the tools become\n' +
   'callable on your NEXT step. Load several names in one call when the task clearly\n' +
-  'needs them. Unknown names are rejected with the list of valid ones.';
+  'needs them. Unknown names are rejected with the list of valid ones.\n' +
+  'Tools NOT listed in the catalog are CORE and ALWAYS active — call them directly,\n' +
+  'NEVER via loadTools (e.g. createComment, listComments, resolveComment,\n' +
+  'editPageText, searchInPage).';
 
 /**
  * Tier + catalogLine for the INLINE ai-chat tools — those defined per-layer in
@@ -121,12 +131,9 @@ export const INLINE_TOOL_TIERS: Record<
   // --- deferred inline ---
   // NOTE: createPage, renamePage, movePage, deletePage, updatePageJson and
   // exportPageMarkdown moved to @docmost/mcp's SHARED_TOOL_SPECS (#294); they
-  // carry their own deferred tier + catalogLine there.
-  updatePageContent: {
-    tier: 'deferred',
-    catalogLine:
-      "updatePageContent — replace a page's body (and optionally title) with new Markdown.",
-  },
+  // carry their own deferred tier + catalogLine there. updatePageContent moved
+  // there too as updatePageMarkdown (#411) — a shared registry spec now, so it
+  // is no longer an inline tier entry.
   listSidebarPages: {
     tier: 'deferred',
     catalogLine:
@@ -138,7 +145,7 @@ export const INLINE_TOOL_TIERS: Record<
   },
   // NOTE: tableInsertRow, tableDeleteRow and tableUpdateCell moved to
   // @docmost/mcp's SHARED_TOOL_SPECS (#294); they carry their own deferred tier +
-  // catalogLine there. getTable stays inline (its MCP name table_get breaks the
+  // catalogLine there. getTable stays inline (its MCP name tableGet breaks the
   // snake_case(inAppKey) convention, so it has no shared spec).
   // NOTE: checkNewComments moved to @docmost/mcp's SHARED_TOOL_SPECS (#294);
   // it carries its own deferred tier + catalogLine there.
@@ -150,7 +157,7 @@ export const INLINE_TOOL_TIERS: Record<
   // NOTE: sharePage moved to @docmost/mcp's SHARED_TOOL_SPECS (#294); it carries
   // its own deferred tier + catalogLine there. transformPage stays inline (its
   // schema deliberately diverges — it omits the deleteComments field the MCP
-  // docmost_transform exposes, a comment-deletion guardrail).
+  // docmostTransform exposes, a comment-deletion guardrail).
   transformPage: {
     tier: 'deferred',
     catalogLine: "transformPage — run a sandboxed JS transform over a page's document.",

apps/server/src/core/auth/strategies/jwt.strategy.spec.ts

@@ -120,3 +120,102 @@ describe('JwtStrategy — provenance derivation', () => {
     expect(req.raw.actor).toBeUndefined();
   });
 });
+
+/**
+ * Provenance derivation on the API-KEY path (jwt.strategy.validateApiKey, #486).
+ *
+ * The access-token path stamped provenance; the API-key path returned early
+ * WITHOUT it, so an is_agent API key's REST writes recorded no 'agent' marker.
+ * The API-key payload carries no signed claim, so provenance is resolved from the
+ * SERVER-SIDE user returned by ApiKeyService.validateApiKey: isAgent -> 'agent',
+ * otherwise 'user'; aiChatId is always null (an API key has no ai_chats row).
+ *
+ * The enterprise ApiKeyService is not bundled in the OSS build, so the strategy
+ * loads it through an overridable `resolveApiKeyService` seam that we stub here.
+ */
+describe('JwtStrategy — API-key provenance derivation (#486)', () => {
+  function makeApiKeyStrategy(validateApiKeyImpl: (p: any) => Promise<any>) {
+    const userRepo: any = { findById: jest.fn() };
+    const workspaceRepo: any = { findById: jest.fn() };
+    const userSessionRepo: any = { findActiveById: jest.fn() };
+    const sessionActivityService: any = { trackActivity: jest.fn() };
+    const environmentService: any = { getAppSecret: () => 'test-secret' };
+    const moduleRef: any = {};
+
+    const strategy = new JwtStrategy(
+      userRepo,
+      workspaceRepo,
+      userSessionRepo,
+      sessionActivityService,
+      environmentService,
+      moduleRef,
+    );
+    // Stub the EE ApiKeyService seam (the real module is not in the OSS build).
+    const validateApiKey = jest.fn(validateApiKeyImpl);
+    jest
+      .spyOn(strategy as any, 'resolveApiKeyService')
+      .mockReturnValue({ validateApiKey });
+    return { strategy, validateApiKey };
+  }
+
+  const makeReq = () => ({ raw: {} as Record<string, any> });
+  const apiKeyPayload = () => ({
+    sub: 'svc-1',
+    workspaceId: 'ws-1',
+    apiKeyId: 'key-1',
+    type: JwtType.API_KEY,
+  });
+
+  it("stamps actor='agent' for an is_agent API key (from the validated user)", async () => {
+    const validated = {
+      user: { id: 'svc-1', isAgent: true },
+      workspace: { id: 'ws-1' },
+    };
+    const { strategy, validateApiKey } = makeApiKeyStrategy(
+      async () => validated,
+    );
+    const req = makeReq();
+
+    const result = await strategy.validate(req, apiKeyPayload() as any);
+
+    expect(validateApiKey).toHaveBeenCalledTimes(1);
+    expect(req.raw.actor).toBe('agent');
+    // API keys carry no internal ai_chats row -> null.
+    expect(req.raw.aiChatId).toBeNull();
+    // The validated auth object is returned unchanged (req.user shape preserved).
+    expect(result).toBe(validated);
+  });
+
+  it("stamps actor='user' for an ordinary (non-agent) API key", async () => {
+    const { strategy } = makeApiKeyStrategy(async () => ({
+      user: { id: 'u-1', isAgent: false },
+      workspace: { id: 'ws-1' },
+    }));
+    const req = makeReq();
+
+    await strategy.validate(req, apiKeyPayload() as any);
+
+    expect(req.raw.actor).toBe('user');
+    expect(req.raw.aiChatId).toBeNull();
+  });
+
+  it('throws Unauthorized (and stamps nothing) when the EE module is missing', async () => {
+    const userRepo: any = { findById: jest.fn() };
+    const strategy = new JwtStrategy(
+      userRepo,
+      { findById: jest.fn() } as any,
+      { findActiveById: jest.fn() } as any,
+      { trackActivity: jest.fn() } as any,
+      { getAppSecret: () => 'test-secret' } as any,
+      {} as any,
+    );
+    // EE not bundled: the seam returns null.
+    jest.spyOn(strategy as any, 'resolveApiKeyService').mockReturnValue(null);
+    const req = makeReq();
+
+    await expect(
+      strategy.validate(req, apiKeyPayload() as any),
+    ).rejects.toThrow(UnauthorizedException);
+    expect(req.raw.actor).toBeUndefined();
+  });
+});

apps/server/src/core/auth/strategies/jwt.strategy.ts

@@ -102,28 +102,49 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
   }
 
   private async validateApiKey(req: any, payload: JwtApiKeyPayload) {
-    let ApiKeyModule: any;
-    let isApiKeyModuleReady = false;
+    const apiKeyService = this.resolveApiKeyService();
+    if (!apiKeyService) {
+      throw new UnauthorizedException('Enterprise API Key module missing');
+    }
 
+    const result = await apiKeyService.validateApiKey(payload);
+
+    // Stamp the agent-edit provenance for the API-KEY path too (#486). Unlike the
+    // access-token path above, it CANNOT be resolved before this point: the
+    // API-key payload carries no signed actor/aiChatId claim, and the user (with
+    // its isAgent flag) is unknown until the key is validated. Claim semantics for
+    // API keys: an is_agent API key (an agent service account) stamps 'agent' on
+    // every REST write; an ordinary API key resolves to 'user'. An API key has no
+    // internal ai_chats row, so aiChatId is always null. Derived from the
+    // SERVER-SIDE user (never a client field), so an 'agent' badge is unspoofable
+    // — mirroring the access-token path. Passing `null` for the claim means the
+    // actor is decided solely by user.isAgent.
+    const provenance = resolveProvenance((result as any)?.user, null);
+    req.raw.actor = provenance.actor;
+    req.raw.aiChatId = provenance.aiChatId;
+
+    return result;
+  }
+
+  /**
+   * Resolve the enterprise ApiKeyService, or `null` when the EE module is not
+   * bundled in this build (community build). Extracted as an overridable seam so
+   * the API-key provenance stamping can be unit-tested without the EE package
+   * present (docmost is OSS + a separate EE bundle; `require` of the EE path
+   * throws here). Any load/resolve error is treated as "module missing".
+   */
+  protected resolveApiKeyService(): {
+    validateApiKey: (payload: JwtApiKeyPayload) => Promise<unknown>;
+  } | null {
     try {
       // eslint-disable-next-line @typescript-eslint/no-require-imports
-      ApiKeyModule = require('./../../../ee/api-key/api-key.service');
-      isApiKeyModuleReady = true;
+      const ApiKeyModule = require('./../../../ee/api-key/api-key.service');
+      return this.moduleRef.get(ApiKeyModule.ApiKeyService, { strict: false });
     } catch (err) {
       this.logger.debug(
         'API Key module requested but enterprise module not bundled in this build',
       );
-      isApiKeyModuleReady = false;
+      return null;
     }
-
-    if (isApiKeyModuleReady) {
-      const ApiKeyService = this.moduleRef.get(ApiKeyModule.ApiKeyService, {
-        strict: false,
-      });
-
-      return ApiKeyService.validateApiKey(payload);
-    }
-
-    throw new UnauthorizedException('Enterprise API Key module missing');
   }
 }

apps/server/src/core/page/dto/move-page.dto.spec.ts

@@ -17,9 +17,10 @@ import { MovePageDto } from './move-page.dto';
 //     a valid ordering key the server itself generated would be refused on move.
 //
 // The tests below assert the CORRECT contract: any key the generator can produce
-// must satisfy the DTO. The genuinely-failing case is marked `test.failing` so the
-// suite stays green while locking the bug; it flips red (alerting us) once the DTO
-// bounds are widened to cover the generator's real range.
+// must satisfy the DTO. FIXED (#495 item 9): the DTO now validates `position` by
+// CHARSET ([0-9A-Za-z], the generator's base-62 alphabet) instead of the wrong
+// @MaxLength(12) length bound, so dense between-inserts are accepted; the former
+// `test.failing` bug-lock is now a passing assertion.
 
 function constraintErrors(position: unknown) {
   const dto = plainToInstance(MovePageDto, {
@@ -47,24 +48,33 @@ describe('MovePageDto.position vs generateJitteredKeyBetween parity', () => {
     expect(hasError(errors, 'position')).toBe(false);
   });
 
-  // BUG LOCK: dense between-inserts produce keys longer than 12 chars, which
-  // MaxLength(12) rejects even though they are valid ordering keys. This SHOULD
-  // pass; it currently fails. Flips green when the DTO bound is fixed.
-  test.failing(
-    'accepts dense between-inserted keys (currently rejected by MaxLength(12))',
-    async () => {
-      let lo = generateJitteredKeyBetween(null, null);
-      let hi = generateJitteredKeyBetween(lo, null);
-      // Repeatedly insert just above `lo`, shrinking the gap so the key grows.
-      let longest = lo;
-      for (let i = 0; i < 40; i++) {
-        const mid = generateJitteredKeyBetween(lo, hi);
-        if (mid.length > longest.length) longest = mid;
-        hi = mid;
-      }
-      expect(longest.length).toBeGreaterThan(12); // sanity: we produced a long key
-      const errors = await constraintErrors(longest);
-      expect(hasError(errors, 'position')).toBe(false);
-    },
-  );
+  // FIXED: dense between-inserts produce keys longer than 12 chars, which the old
+  // MaxLength(12) rejected even though they are valid ordering keys. Now accepted.
+  it('accepts dense between-inserted keys longer than 12 chars', async () => {
+    let lo = generateJitteredKeyBetween(null, null);
+    let hi = generateJitteredKeyBetween(lo, null);
+    // Repeatedly insert just above `lo`, shrinking the gap so the key grows. The
+    // generator is JITTERED (random), so use enough iterations that the longest
+    // key reliably clears the old 12-char bound: measured min-over-50-trials is
+    // ~11 at 40 iterations (flaky) but ~36 at 200 (robust margin).
+    let longest = lo;
+    for (let i = 0; i < 200; i++) {
+      const mid = generateJitteredKeyBetween(lo, hi);
+      if (mid.length > longest.length) longest = mid;
+      hi = mid;
+    }
+    expect(longest.length).toBeGreaterThan(12); // sanity: we produced a long key
+    const errors = await constraintErrors(longest);
+    expect(hasError(errors, 'position')).toBe(false);
+  });
+
+  // The charset guard replaces the length bound: reject anything outside the
+  // generator's [0-9A-Za-z] alphabet (control chars, separators, injection) and
+  // the empty string, while still accepting every real key.
+  it('rejects a position with characters outside the fractional-index alphabet', async () => {
+    for (const bad of ['a0/b', 'a b', 'a\n0', 'a.b', '', "a';--"]) {
+      const errors = await constraintErrors(bad);
+      expect(hasError(errors, 'position')).toBe(true);
+    }
+  });
 });

apps/server/src/core/page/dto/move-page.dto.ts

@@ -1,8 +1,8 @@
 import {
   IsString,
   IsOptional,
-  MinLength,
   MaxLength,
+  Matches,
   IsNotEmpty,
 } from 'class-validator';
 
@@ -10,9 +10,19 @@ export class MovePageDto {
   @IsString()
   pageId: string;
 
+  // `position` is a fractional-indexing key from `generateJitteredKeyBetween`
+  // (the SAME generator page.service uses). Validate by CHARSET, not length: the
+  // generator's default base-62 alphabet is [0-9A-Za-z], and DENSE between-inserts
+  // legitimately grow a key well past a dozen chars (measured >40), so the old
+  // @MinLength(5)/@MaxLength(12) bounds wrongly 400'd valid ordering keys the
+  // server itself produced (Gitea #139 item 6). The charset regex rejects control
+  // chars / separators / injection, and a generous MaxLength stays only as a
+  // DoS guard — far above any realistic key, so it never rejects a real move.
   @IsString()
-  @MinLength(5)
-  @MaxLength(12)
+  @Matches(/^[0-9A-Za-z]+$/, {
+    message: 'position must be a fractional-index key ([0-9A-Za-z])',
+  })
+  @MaxLength(256)
   position: string;
 
   @IsOptional()

apps/server/src/core/page/dto/page-identity.dto.spec.ts

@@ -0,0 +1,49 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { PageIdDto } from './page.dto';
+
+// #435: PageIdDto.pageId carries a page's DOUBLE identity (internal UUID OR
+// public 10-char slugId), both as bare strings. The DTO must accept exactly
+// those two FORMATS and reject a malformed / swapped identity at the boundary.
+async function pageIdErrors(pageId: unknown) {
+  const dto = plainToInstance(PageIdDto, { pageId });
+  const errors = await validate(dto as object);
+  return errors.some((e) => e.property === 'pageId');
+}
+
+const UUID = '019f499a-9f8c-7d68-b7be-ce100d7c6c56';
+const SLUG = 'aB3xQ7kR2p';
+
+describe('PageIdDto pageId format validation', () => {
+  it('accepts a canonical page UUID', async () => {
+    expect(await pageIdErrors(UUID)).toBe(false);
+  });
+
+  it('accepts a 10-char slugId', async () => {
+    expect(await pageIdErrors(SLUG)).toBe(false);
+  });
+
+  it('rejects a truncated / wrong-length slug', async () => {
+    expect(await pageIdErrors('aB3xQ7kR2')).toBe(true); // 9 chars
+    expect(await pageIdErrors('aB3xQ7kR2pX')).toBe(true); // 11 chars
+  });
+
+  it('rejects a slug with an illegal character', async () => {
+    expect(await pageIdErrors('aB3xQ7kR2!')).toBe(true);
+  });
+
+  it('rejects a full URL / path-shaped identity (not the bare id)', async () => {
+    expect(await pageIdErrors(`my-page-title-${SLUG}`)).toBe(true);
+    expect(await pageIdErrors(`https://x/p/${SLUG}`)).toBe(true);
+  });
+
+  it('rejects a malformed UUID', async () => {
+    expect(await pageIdErrors('019f499a-9f8c-7d68-b7be')).toBe(true);
+    expect(await pageIdErrors('not-a-uuid-at-all-really')).toBe(true);
+  });
+
+  it('rejects an empty string', async () => {
+    expect(await pageIdErrors('')).toBe(true);
+  });
+});

apps/server/src/core/page/dto/page-identity.validator.ts

@@ -0,0 +1,39 @@
+import { applyDecorators } from '@nestjs/common';
+import { Matches, ValidationOptions } from 'class-validator';
+
+/**
+ * A page identity at the API boundary is EITHER the internal page UUID or the
+ * public 10-char slugId (page.repo.findById matches a non-UUID input as a
+ * slugId). Both arrive as bare strings, which is exactly how the two got swapped
+ * silently (incident family #435). This regex pins the two accepted FORMATS so a
+ * malformed / cross-wired identity (a truncated slug, a full URL, an email, an
+ * id from another entity kind that isn't even shaped like either) is rejected at
+ * the boundary instead of falling through to a confusing 404.
+ *
+ *   - UUID:    canonical 8-4-4-4-12 hex (version-agnostic — page ids are UUIDv7,
+ *              so only the shape/length is enforced, matching the MCP's UUID_RE
+ *              and the server's isValidUUID acceptance).
+ *   - slugId:  exactly 10 chars over [0-9A-Za-z] (nanoid `generateSlugId`).
+ *
+ * The two are disjoint (a UUID is 36 chars WITH dashes, a slugId 10 chars
+ * WITHOUT), so a value can only satisfy one branch.
+ */
+export const PAGE_ID_OR_SLUG_ID_REGEX =
+  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9A-Za-z]{10})$/i;
+
+/**
+ * Validate that a DTO string field is a well-formed page identity (page UUID OR
+ * 10-char slugId). Composed decorator so the same format rule is applied
+ * consistently wherever a DTO accepts a `pageId` that may be either form.
+ */
+export function IsPageIdOrSlugId(
+  validationOptions?: ValidationOptions,
+): PropertyDecorator {
+  return applyDecorators(
+    Matches(PAGE_ID_OR_SLUG_ID_REGEX, {
+      message:
+        'pageId must be a page UUID or a 10-character slugId',
+      ...validationOptions,
+    }),
+  );
+}

apps/server/src/core/page/dto/page.dto.ts

@@ -9,10 +9,16 @@ import {
 import { Transform } from 'class-transformer';
 
 import { ContentFormat } from './create-page.dto';
+import { IsPageIdOrSlugId } from './page-identity.validator';
 
 export class PageIdDto {
   @IsString()
   @IsNotEmpty()
+  // Format-validate the double identity (#435): accept only a page UUID or a
+  // 10-char slugId so a malformed / swapped identity is rejected at the boundary
+  // rather than passed to the repo as a bare string. Base for PageInfoDto,
+  // DeletePageDto, BacklinksListDto, AddLabelsDto/RemoveLabelDto, etc.
+  @IsPageIdOrSlugId()
   pageId: string;
 }
 

apps/server/src/core/page/services/spec/temporary-note-cleanup.service.spec.ts

@@ -1,19 +1,38 @@
 import { TemporaryNoteCleanupService } from '../temporary-note-cleanup.service';
 
 /**
- * Chainable Kysely stub that records every `.where(...)` call so the test can
- * assert the sweep only selects armed, expired, not-yet-trashed notes. The
- * terminal `.execute()` resolves the configured expired rows (the batch SELECT);
- * `.executeTakeFirst()` resolves the per-row deadline re-read done just before
- * each `removePage`. By default the re-read reports the note as still armed and
- * still expired (epoch deadline < now), so the sweep proceeds to delete it;
- * tests override `reReadFirst` to simulate a concurrent "Make permanent".
+ * Chainable Kysely stub for the temporary-note sweep.
+ *
+ * `this.db` serves the non-locking candidate SELECT (selectFrom/select/where/
+ * limit/execute -> the configured expired rows) AND `.transaction().execute(cb)`,
+ * which runs `cb` with a separate `trx` builder. The `trx` builder serves the
+ * per-row LOCKED re-check (selectFrom/select/where/forUpdate/skipLocked/
+ * executeTakeFirst). `lockedRows` drives what that locked re-check returns per
+ * candidate — an id/creator/workspace row means "still expired, delete it";
+ * `undefined` means the predicate no longer matched (made permanent / re-armed /
+ * already trashed) or the row was SKIP-LOCKED by another worker, so it is skipped.
  */
-function makeDbStub(expiredRows: any[]) {
+function makeDbStub(expiredRows: any[], lockedRows?: any[]) {
   const whereCalls: any[][] = [];
-  const reReadFirst = jest
-    .fn()
-    .mockResolvedValue({ temporaryExpiresAt: new Date(0), deletedAt: null });
+  const locked = [
+    ...(lockedRows ??
+      expiredRows.map((r) => ({
+        id: r.id,
+        creatorId: r.creatorId,
+        workspaceId: r.workspaceId,
+      }))),
+  ];
+  const lockedTakeFirst = jest.fn(() => Promise.resolve(locked.shift()));
+  const forUpdate = jest.fn(() => trxBuilder);
+  const skipLocked = jest.fn(() => trxBuilder);
+  const trxBuilder: any = {
+    selectFrom: jest.fn(() => trxBuilder),
+    select: jest.fn(() => trxBuilder),
+    where: jest.fn(() => trxBuilder),
+    forUpdate,
+    skipLocked,
+    executeTakeFirst: lockedTakeFirst,
+  };
   const builder: any = {
     selectFrom: jest.fn(() => builder),
     select: jest.fn(() => builder),
@@ -23,9 +42,11 @@ function makeDbStub(expiredRows: any[]) {
     }),
     limit: jest.fn(() => builder),
     execute: jest.fn().mockResolvedValue(expiredRows),
-    executeTakeFirst: reReadFirst,
+    transaction: jest.fn(() => ({
+      execute: (cb: (trx: any) => Promise<any>) => Promise.resolve(cb(trxBuilder)),
+    })),
   };
-  return { builder, whereCalls, reReadFirst };
+  return { builder, whereCalls, lockedTakeFirst, forUpdate, skipLocked };
 }
 
 describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
@@ -52,20 +73,36 @@ describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
     expect(builder.limit.mock.calls[0][0]).toBeGreaterThan(0);
   });
 
-  it('soft-deletes each expired note via removePage, attributed to its creator', async () => {
+  it('soft-deletes each expired note via removePage under a row lock, attributed to its creator', async () => {
     const expired = [
       { id: 'p1', creatorId: 'u1', workspaceId: 'w1' },
       { id: 'p2', creatorId: 'u2', workspaceId: 'w1' },
     ];
-    const { builder } = makeDbStub(expired);
+    const { builder, forUpdate, skipLocked } = makeDbStub(expired);
     const pageRepo = { removePage: jest.fn().mockResolvedValue(undefined) } as any;
     const service = new TemporaryNoteCleanupService(builder, pageRepo);
 
     await service.sweepExpiredTemporaryNotes();
 
     expect(pageRepo.removePage).toHaveBeenCalledTimes(2);
-    expect(pageRepo.removePage).toHaveBeenNthCalledWith(1, 'p1', 'u1', 'w1');
-    expect(pageRepo.removePage).toHaveBeenNthCalledWith(2, 'p2', 'u2', 'w1');
+    // The 4th arg is the locking transaction — the delete runs inside it.
+    expect(pageRepo.removePage).toHaveBeenNthCalledWith(
+      1,
+      'p1',
+      'u1',
+      'w1',
+      expect.anything(),
+    );
+    expect(pageRepo.removePage).toHaveBeenNthCalledWith(
+      2,
+      'p2',
+      'u2',
+      'w1',
+      expect.anything(),
+    );
+    // The re-check acquired a FOR UPDATE SKIP LOCKED lock (once per candidate).
+    expect(forUpdate).toHaveBeenCalledTimes(2);
+    expect(skipLocked).toHaveBeenCalledTimes(2);
   });
 
   it('continues past a failing note (one bad removePage does not abort the sweep)', async () => {
@@ -86,60 +123,29 @@ describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
       service.sweepExpiredTemporaryNotes(),
     ).resolves.toBeUndefined();
     expect(pageRepo.removePage).toHaveBeenCalledTimes(2);
-    expect(pageRepo.removePage).toHaveBeenNthCalledWith(2, 'good', 'u2', 'w1');
+    expect(pageRepo.removePage).toHaveBeenNthCalledWith(
+      2,
+      'good',
+      'u2',
+      'w1',
+      expect.anything(),
+    );
   });
 
-  it('does NOT trash a note made permanent in the race window', async () => {
-    // The batch SELECT saw the note as expired, but before its turn in the loop
-    // the user clicked "Make permanent" (temporary_expires_at -> null). The
-    // deadline re-read must catch this and skip the delete so the keep wins.
+  it('does NOT trash a note made permanent / re-armed / already trashed (locked re-check returns nothing)', async () => {
+    // The batch SELECT saw the note as expired, but by the time the LOCKED
+    // re-check runs the row no longer matches the still-armed+expired+not-trashed
+    // predicate (make-permanent, re-arm to a future deadline, or already trashed),
+    // OR another worker holds the row (SKIP LOCKED). In every case the locked
+    // SELECT returns nothing and the delete is skipped so the keep/other worker wins.
     const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
-    const { builder, reReadFirst } = makeDbStub(expired);
-    reReadFirst.mockResolvedValueOnce({
-      temporaryExpiresAt: null,
-      deletedAt: null,
-    });
+    const { builder, lockedTakeFirst } = makeDbStub(expired, [undefined]);
     const pageRepo = { removePage: jest.fn() } as any;
     const service = new TemporaryNoteCleanupService(builder, pageRepo);
 
     await service.sweepExpiredTemporaryNotes();
 
-    expect(reReadFirst).toHaveBeenCalledTimes(1);
-    expect(pageRepo.removePage).not.toHaveBeenCalled();
-  });
-
-  it('skips a note already trashed since the batch SELECT', async () => {
-    const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
-    const { builder, reReadFirst } = makeDbStub(expired);
-    reReadFirst.mockResolvedValueOnce({
-      temporaryExpiresAt: new Date(0),
-      deletedAt: new Date(),
-    });
-    const pageRepo = { removePage: jest.fn() } as any;
-    const service = new TemporaryNoteCleanupService(builder, pageRepo);
-
-    await service.sweepExpiredTemporaryNotes();
-
-    expect(pageRepo.removePage).not.toHaveBeenCalled();
-  });
-
-  it('does NOT trash a note re-armed to a future deadline in the race window', async () => {
-    // The batch SELECT saw the note as expired, but before its turn in the loop
-    // the user disarmed it and re-armed it to a fresh, still-future deadline
-    // (temporary_expires_at -> now + 1h). The deadline re-read must catch that
-    // the note is no longer expired and skip the delete so the keep wins.
-    const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
-    const { builder, reReadFirst } = makeDbStub(expired);
-    reReadFirst.mockResolvedValueOnce({
-      temporaryExpiresAt: new Date(Date.now() + 60 * 60 * 1000),
-      deletedAt: null,
-    });
-    const pageRepo = { removePage: jest.fn() } as any;
-    const service = new TemporaryNoteCleanupService(builder, pageRepo);
-
-    await service.sweepExpiredTemporaryNotes();
-
-    expect(reReadFirst).toHaveBeenCalledTimes(1);
+    expect(lockedTakeFirst).toHaveBeenCalledTimes(1);
     expect(pageRepo.removePage).not.toHaveBeenCalled();
   });
 
@@ -151,4 +157,31 @@ describe('TemporaryNoteCleanupService.sweepExpiredTemporaryNotes', () => {
     await service.sweepExpiredTemporaryNotes();
     expect(pageRepo.removePage).not.toHaveBeenCalled();
   });
+
+  it('sweeps once on application bootstrap (catches notes expired during downtime)', async () => {
+    const expired = [{ id: 'p1', creatorId: 'u1', workspaceId: 'w1' }];
+    const { builder } = makeDbStub(expired);
+    const pageRepo = { removePage: jest.fn().mockResolvedValue(undefined) } as any;
+    const service = new TemporaryNoteCleanupService(builder, pageRepo);
+
+    await service.onApplicationBootstrap();
+
+    expect(pageRepo.removePage).toHaveBeenCalledTimes(1);
+    expect(pageRepo.removePage).toHaveBeenCalledWith(
+      'p1',
+      'u1',
+      'w1',
+      expect.anything(),
+    );
+  });
+
+  it('a startup-sweep failure never blocks application boot', async () => {
+    const { builder } = makeDbStub([]);
+    // Make the candidate SELECT throw to simulate a boot-time DB hiccup.
+    builder.execute.mockRejectedValueOnce(new Error('db not ready'));
+    const pageRepo = { removePage: jest.fn() } as any;
+    const service = new TemporaryNoteCleanupService(builder, pageRepo);
+
+    await expect(service.onApplicationBootstrap()).resolves.toBeUndefined();
+  });
 });

apps/server/src/core/page/services/temporary-note-cleanup.service.ts

@@ -1,8 +1,13 @@
-import { Injectable, Logger } from '@nestjs/common';
+import {
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+} from '@nestjs/common';
 import { Interval } from '@nestjs/schedule';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { executeTx } from '@docmost/db/utils';
 
 /**
  * Background sweeper for temporary notes ("structure or die"). A note whose
@@ -11,7 +16,7 @@ import { PageRepo } from '@docmost/db/repos/page/page.repo';
  * TrashCleanupService; `@nestjs/schedule` is already enabled globally.
  */
 @Injectable()
-export class TemporaryNoteCleanupService {
+export class TemporaryNoteCleanupService implements OnApplicationBootstrap {
   private readonly logger = new Logger(TemporaryNoteCleanupService.name);
 
   // Cap a single sweep so a large backlog (e.g. many notes created during
@@ -24,6 +29,20 @@ export class TemporaryNoteCleanupService {
     private readonly pageRepo: PageRepo,
   ) {}
 
+  // Sweep once at startup so notes that expired during downtime are trashed
+  // right away instead of waiting up to an hour for the first @Interval tick.
+  // Best-effort: never let a startup-sweep failure block application boot.
+  async onApplicationBootstrap() {
+    try {
+      await this.sweepExpiredTemporaryNotes();
+    } catch (error) {
+      this.logger.error(
+        'Temporary-note startup sweep failed',
+        error instanceof Error ? error.stack : undefined,
+      );
+    }
+  }
+
   // Hourly granularity: lifetimes are configured in hours, so a sub-hour
   // overshoot past the deadline is acceptable.
   @Interval('temporary-note-cleanup', 60 * 60 * 1000)
@@ -31,9 +50,11 @@ export class TemporaryNoteCleanupService {
     try {
       const now = new Date();
 
+      // Candidate ids (non-locking). The authoritative re-check happens per row
+      // under a row lock below, so this cheap pass just bounds the batch.
       const expired = await this.db
         .selectFrom('pages')
-        .select(['id', 'creatorId', 'workspaceId'])
+        .select(['id'])
         .where('temporaryExpiresAt', 'is not', null)
         .where('temporaryExpiresAt', '<', now)
         .where('deletedAt', 'is', null) // not already in trash
@@ -41,50 +62,53 @@ export class TemporaryNoteCleanupService {
         .execute();
 
       let trashed = 0;
-      for (const page of expired) {
+      for (const candidate of expired) {
         try {
-          // Re-check the deadline at deletion time. The SELECT above is not
-          // transactional, so a user may click "Make permanent"
-          // (toggleTemporary sets temporary_expires_at = null) in the window
-          // between the SELECT and this per-row removePage. removePage deletes
-          // by id with only a `deletedAt IS NULL` filter and never re-reads the
-          // deadline, so without this guard a concurrently-kept note would
-          // still be trashed. Re-read the row and skip it unless it is still
-          // armed AND still expired, so a concurrent make-permanent wins.
-          const current = await this.db
-            .selectFrom('pages')
-            .select(['temporaryExpiresAt', 'deletedAt'])
-            .where('id', '=', page.id)
-            .executeTakeFirst();
+          const didTrash = await executeTx(this.db, async (trx) => {
+            // Re-check the row UNDER A LOCK inside the transaction. `FOR UPDATE
+            // SKIP LOCKED`:
+            //  - serialises against a concurrent "Make permanent"
+            //    (toggleTemporary UPDATE takes the same row lock): if it commits
+            //    first, the deadline predicate below no longer matches and we
+            //    skip; if we lock first, it waits until this delete commits.
+            //  - SKIP LOCKED lets a second worker/instance skip a row another
+            //    sweeper already claimed instead of blocking on it (no double
+            //    processing, no thundering herd).
+            // The predicate re-asserts still-armed AND still-expired AND
+            // not-already-trashed, so a make-permanent / prior sweep drops the row.
+            const locked = await trx
+              .selectFrom('pages')
+              .select(['id', 'creatorId', 'workspaceId'])
+              .where('id', '=', candidate.id)
+              .where('temporaryExpiresAt', 'is not', null)
+              .where('temporaryExpiresAt', '<', now)
+              .where('deletedAt', 'is', null)
+              .forUpdate()
+              .skipLocked()
+              .executeTakeFirst();
 
-          if (
-            !current ||
-            current.deletedAt !== null ||
-            current.temporaryExpiresAt === null ||
-            new Date(current.temporaryExpiresAt) >= now
-          ) {
-            // Made permanent, already trashed, or no longer expired since the
-            // SELECT — leave it alone.
-            continue;
-          }
+            if (!locked) return false;
 
-          // Reuse the exact soft-delete path: recursive over children, removes
-          // shares in a transaction, and emits PAGE_SOFT_DELETED (tree
-          // invalidation + watcher notifications). Attribute the automatic
-          // deletion to the note's creator (no schema change). Both the SELECT
-          // above and removePage filter `deletedAt IS NULL`, so a double sweep
-          // is idempotent.
-          await this.pageRepo.removePage(
-            page.id,
-            // creatorId is set on every created page; a temporary note always
-            // has one. Cast to satisfy the non-null deletedById parameter.
-            page.creatorId as string,
-            page.workspaceId,
-          );
-          trashed++;
+            // Reuse the exact soft-delete path (recursive children + share
+            // removal + PAGE_SOFT_DELETED broadcast), running IN this locked
+            // transaction so the delete is atomic with the re-check and cannot
+            // deadlock on a nested independent transaction. The broadcast is
+            // deferred by removePage to this transaction's commit. Attribute the
+            // automatic deletion to the note's creator (no schema change).
+            await this.pageRepo.removePage(
+              locked.id,
+              // creatorId is set on every created page; a temporary note always
+              // has one. Cast to satisfy the non-null deletedById parameter.
+              locked.creatorId as string,
+              locked.workspaceId,
+              trx,
+            );
+            return true;
+          });
+          if (didTrash) trashed++;
         } catch (error) {
           this.logger.error(
-            `Failed to trash expired temporary note ${page.id}`,
+            `Failed to trash expired temporary note ${candidate.id}`,
             error instanceof Error ? error.stack : undefined,
           );
         }

apps/server/src/core/search/dto/search-response.dto.ts

@@ -12,3 +12,22 @@ export class SearchResponseDto {
   updatedAt: Date;
   space: Partial<Space>;
 }
+
+// Response shape for the opt-in agent-lookup mode (#443, `substring: true`).
+// Additive to the FTS response: carries the location (`path`), a windowed
+// `snippet` around the first match and a per-response sort `score`. The MCP
+// layer maps `id → pageId`; `slugId` is never exposed.
+export class SearchLookupResponseDto {
+  id: string;
+  slugId: string;
+  title: string;
+  parentPageId: string | null;
+  // Ancestor titles from the space root down to the direct parent; [] for a
+  // root page.
+  path: string[];
+  // ~300–500 chars around the first match (or a leading text window / extended
+  // ts_headline fallback).
+  snippet: string;
+  // 0..1 float, meaningful ONLY for sorting within one response.
+  score: number;
+}

apps/server/src/core/search/dto/search.dto.ts

@@ -30,6 +30,31 @@ export class SearchDTO {
   @IsOptional()
   @IsNumber()
   offset?: number;
+
+  // --- Opt-in agent-lookup mode (#443). ------------------------------------
+  // These fields are ADDITIVE and default-off: a web client that sends none of
+  // them gets byte-identical FTS behaviour and result shape. They are only read
+  // by the substring/path/snippet code path in SearchService.searchPage.
+  //
+  // NOTE (standalone stdio vs stock upstream): stock upstream validates this DTO
+  // with `whitelist: true`, so an older server silently strips these unknown
+  // fields and the request degrades gracefully to the plain FTS behaviour.
+
+  // Enables the hybrid substring branch (title + text_content LIKE) merged with
+  // the existing FTS branch, plus tiered ranking, path and windowed snippet.
+  @IsOptional()
+  @IsBoolean()
+  substring?: boolean;
+
+  // Restrict the search to a page and all of its descendants (inclusive).
+  @IsOptional()
+  @IsString()
+  parentPageId?: string;
+
+  // Match titles only; do not scan text_content.
+  @IsOptional()
+  @IsBoolean()
+  titleOnly?: boolean;
 }
 
 export class SearchShareDTO extends SearchDTO {

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

@@ -60,6 +60,12 @@ export class SearchController {
       }
     }
 
+    // #443 graceful degradation: on EE/Typesense instances the request routes to
+    // the Typesense backend, which does NOT implement the opt-in agent-lookup
+    // mode. The `substring`/`parentPageId`/`titleOnly` fields are silently ignored
+    // and the response carries no `path`/`snippet`/`score` and no substring/tier
+    // ranking — it degrades to plain Typesense FTS. The native lookup mode below
+    // is Postgres-search-driver only.
     if (this.environmentService.getSearchDriver() === 'typesense') {
       return this.searchTypesense(searchDto, {
         userId: user.id,

apps/server/src/core/search/search.service.lookup.spec.ts

@@ -0,0 +1,95 @@
+import {
+  computeLookupScore,
+  escapeLikePattern,
+  SearchLookupTier,
+} from './search.service';
+
+/**
+ * Pure-function coverage for the #443 agent-lookup helpers:
+ *  - escapeLikePattern: LIKE-metacharacter escaping so `%`/`_`/`\` are literals
+ *    (the acceptance-table requirement that a query of `%` or `_` does NOT match
+ *    everything);
+ *  - computeLookupScore: the tiered 0..1 ranking score, where a stronger tier
+ *    always outranks a weaker one regardless of the in-tier secondary signal.
+ *
+ * The DB-touching branch (substring UNION FTS, path CTE, snippet window) is
+ * covered by the integration spec against the real schema.
+ */
+describe('escapeLikePattern', () => {
+  it('escapes the LIKE metacharacters % _ and \\', () => {
+    expect(escapeLikePattern('%')).toBe('\\%');
+    expect(escapeLikePattern('_')).toBe('\\_');
+    expect(escapeLikePattern('\\')).toBe('\\\\');
+  });
+
+  it('escapes the backslash FIRST so it does not double-escape %/_', () => {
+    // Input `\%` must become `\\` + `\%` = `\\\%`, not `\\%`.
+    expect(escapeLikePattern('\\%')).toBe('\\\\\\%');
+  });
+
+  it('leaves ordinary technical chars (. - / digits) untouched', () => {
+    expect(escapeLikePattern('backup-srv.local')).toBe('backup-srv.local');
+    expect(escapeLikePattern('10.0.12')).toBe('10.0.12');
+    expect(escapeLikePattern('WB-MGE-30D86B')).toBe('WB-MGE-30D86B');
+    expect(escapeLikePattern('a/b')).toBe('a/b');
+  });
+
+  it('escapes only the metacharacters in a mixed string', () => {
+    expect(escapeLikePattern('50%_off.zip')).toBe('50\\%\\_off.zip');
+  });
+
+  it('is null/undefined-safe', () => {
+    expect(escapeLikePattern(undefined as any)).toBe('');
+    expect(escapeLikePattern(null as any)).toBe('');
+  });
+});
+
+describe('computeLookupScore', () => {
+  it('keeps every score within (0, 1]', () => {
+    for (const tier of [
+      SearchLookupTier.TITLE_EXACT,
+      SearchLookupTier.TITLE_SUBSTRING,
+      SearchLookupTier.TEXT,
+    ]) {
+      for (const secondary of [0, 0.001, 1, 100, 1e6]) {
+        const s = computeLookupScore({ tier, secondary });
+        expect(s).toBeGreaterThan(0);
+        expect(s).toBeLessThanOrEqual(1);
+      }
+    }
+  });
+
+  it('a stronger tier ALWAYS outranks a weaker tier, whatever the secondary', () => {
+    // Weak tier with a huge secondary must still lose to a strong tier with a
+    // tiny secondary — tiers dominate.
+    const strongLowSecondary = computeLookupScore({
+      tier: SearchLookupTier.TITLE_EXACT,
+      secondary: 0,
+    });
+    const weakHighSecondary = computeLookupScore({
+      tier: SearchLookupTier.TEXT,
+      secondary: 1e9,
+    });
+    expect(strongLowSecondary).toBeGreaterThan(weakHighSecondary);
+  });
+
+  it('within a tier a larger secondary sorts higher', () => {
+    const lo = computeLookupScore({
+      tier: SearchLookupTier.TEXT,
+      secondary: 0.1,
+    });
+    const hi = computeLookupScore({
+      tier: SearchLookupTier.TEXT,
+      secondary: 5,
+    });
+    expect(hi).toBeGreaterThan(lo);
+  });
+
+  it('treats a negative/absent secondary as 0', () => {
+    const zero = computeLookupScore({ tier: SearchLookupTier.TEXT, secondary: 0 });
+    expect(computeLookupScore({ tier: SearchLookupTier.TEXT })).toBe(zero);
+    expect(
+      computeLookupScore({ tier: SearchLookupTier.TEXT, secondary: -5 }),
+    ).toBe(zero);
+  });
+});

apps/server/src/core/search/search.service.ts

@@ -1,6 +1,9 @@
 import { Injectable } from '@nestjs/common';
 import { SearchDTO, SearchSuggestionDTO } from './dto/search.dto';
-import { SearchResponseDto } from './dto/search-response.dto';
+import {
+  SearchLookupResponseDto,
+  SearchResponseDto,
+} from './dto/search-response.dto';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
 import { sql } from 'kysely';
@@ -34,6 +37,53 @@ export function buildTsQuery(raw: string): string {
   return tsquery(cleaned + '*');
 }
 
+// Escape the LIKE metacharacters (`%`, `_`, `\`) in a raw user query so every
+// character — including `.`, `-`, `_`, `%`, `/` — is matched LITERALLY by a
+// `col LIKE '%' || q || '%'` predicate. Without this, a query of `%` or `_`
+// would match every row (see the #443 acceptance table). The backslash is the
+// escape char (Postgres LIKE default), so it must be escaped first.
+export function escapeLikePattern(raw: string): string {
+  return (raw ?? '')
+    .replace(/\\/g, '\\\\')
+    .replace(/%/g, '\\%')
+    .replace(/_/g, '\\_');
+}
+
+// Ranking tiers for the agent-lookup mode (#443), highest first. A hit's tier
+// is the strongest way it matched; ties inside a tier break on a secondary
+// signal (FTS rank, or first-match position). The numeric `score` returned to
+// the caller is derived from (tier, secondary) and is meaningful ONLY for
+// ordering within a single response.
+export enum SearchLookupTier {
+  // Title equals the query, case-insensitively.
+  TITLE_EXACT = 3,
+  // Query is a substring of the title.
+  TITLE_SUBSTRING = 2,
+  // Query matched in the text (substring or FTS).
+  TEXT = 1,
+}
+
+export interface RankableHit {
+  tier: SearchLookupTier;
+  // Secondary in-tier signal, higher = better (e.g. ts_rank, or a
+  // position-derived closeness score). Defaults to 0.
+  secondary?: number;
+}
+
+// Map (tier, secondary) → a 0..1 float used ONLY to sort one response.
+//
+// Formula: score = (tier + squash(secondary)) / (maxTier + 1), where
+//   squash(x) = x / (1 + x)  maps any non-negative secondary into [0, 1)
+// so a stronger tier ALWAYS outranks a weaker one regardless of the secondary
+// value, and within a tier a larger secondary sorts higher. maxTier is the top
+// enum value (TITLE_EXACT = 3), so the divisor keeps the result in (0, 1].
+export function computeLookupScore(hit: RankableHit): number {
+  const maxTier = SearchLookupTier.TITLE_EXACT;
+  const secondary = Math.max(0, hit.secondary ?? 0);
+  const squashed = secondary / (1 + secondary);
+  return (hit.tier + squashed) / (maxTier + 1);
+}
+
 @Injectable()
 export class SearchService {
   constructor(
@@ -50,12 +100,19 @@ export class SearchService {
       userId?: string;
       workspaceId: string;
     },
-  ): Promise<{ items: SearchResponseDto[] }> {
+  ): Promise<{ items: SearchResponseDto[] | SearchLookupResponseDto[] }> {
     const { query } = searchParams;
 
     if (query.length < 1) {
       return { items: [] };
     }
+
+    // Opt-in agent-lookup mode (#443). Guarded by the `substring` flag so the
+    // web-UI (which never sets it) keeps byte-identical FTS behaviour below.
+    if (searchParams.substring) {
+      return this.searchPageLookup(searchParams, opts);
+    }
+
     const searchQuery = buildTsQuery(query);
 
     let queryResults = this.db
@@ -175,6 +232,348 @@ export class SearchService {
     return { items: searchResults };
   }
 
+  /**
+   * Agent-lookup search (#443, opt-in via `SearchDTO.substring`).
+   *
+   * ADDITIVE to the FTS path: runs a substring branch (title + optionally
+   * text_content, LIKE with metacharacters escaped) MERGED with the existing
+   * FTS branch, so technical tokens that the `english` tokenizer mangles
+   * (`backup-srv.local`, `10.0.12.5`, `WB-MGE-30D86B`) are still found — even
+   * when `buildTsQuery()` returns '' for a dotted/numeric query. Results carry a
+   * location (`path`), a windowed `snippet` and a per-response `score`.
+   *
+   * The whole method is only reached when `substring: true`; the web-UI never
+   * sets it, so its behaviour is unchanged.
+   */
+  private async searchPageLookup(
+    searchParams: SearchDTO,
+    opts: { userId?: string; workspaceId: string },
+  ): Promise<{ items: SearchLookupResponseDto[] }> {
+    const rawQuery = searchParams.query.trim();
+    if (!rawQuery) {
+      return { items: [] };
+    }
+
+    const limit = Math.min(Math.max(searchParams.limit || 10, 1), 50);
+
+    // Normalize the query the same way as the FTS / suggest path: f_unaccent +
+    // lower, done in SQL. `q` is the escaped LIKE pattern body (literal chars).
+    const likeBody = escapeLikePattern(rawQuery);
+    // Compare against `LOWER(f_unaccent(col))`; unaccent+lower the needle too.
+    const needle = sql<string>`LOWER(f_unaccent(${rawQuery}))`;
+    const likePattern = sql<string>`LOWER(f_unaccent(${'%' + likeBody + '%'}))`;
+    const tsQuery = buildTsQuery(rawQuery);
+    const hasTsQuery = tsQuery.length > 0;
+
+    // --- Resolve the space scope. ---------------------------------------------
+    // Mirrors searchPage: explicit spaceId, else the authenticated user's member
+    // spaces. The share path is not exposed to this opt-in mode.
+    let spaceIds: string[] = [];
+    if (searchParams.spaceId) {
+      spaceIds = [searchParams.spaceId];
+    } else if (opts.userId) {
+      spaceIds = await this.spaceMemberRepo.getUserSpaceIds(opts.userId);
+    } else {
+      return { items: [] };
+    }
+    if (spaceIds.length === 0) {
+      return { items: [] };
+    }
+
+    // --- Optional parentPageId subtree scope (inclusive). ---------------------
+    // Reuse the same recursive-descendants pattern used for share-scope.
+    let descendantIds: string[] | null = null;
+    if (searchParams.parentPageId) {
+      const descendants = await this.pageRepo.getPageAndDescendants(
+        searchParams.parentPageId,
+        { includeContent: false },
+      );
+      descendantIds = descendants.map((p: any) => p.id);
+      if (descendantIds.length === 0) {
+        return { items: [] };
+      }
+    }
+
+    // --- Candidate query: substring (title + text) UNION FTS. -----------------
+    // We compute everything the ranker needs in SQL and pull only small columns
+    // (never the whole text_content) into Node:
+    //   - titleExact / titleSub: tier signals
+    //   - textMatchPos: 1-based position of the first text match (0 = none)
+    //   - ftsRank: ts_rank for the FTS secondary signal (0 when no tsquery)
+    //   - snippet: windowed ~500 chars around the first text match, or a leading
+    //     text window (title-only hit), or an extended ts_headline fallback.
+    const N_BEFORE = 60; // chars of context before the first match
+    const SNIPPET_LEN = 500;
+
+    let candidates = this.db
+      .selectFrom('pages')
+      .select([
+        'pages.id as id',
+        'pages.slugId as slugId',
+        'pages.title as title',
+        'pages.parentPageId as parentPageId',
+        // Tier signals.
+        sql<boolean>`LOWER(f_unaccent(coalesce(pages.title, ''))) = ${needle}`.as(
+          'titleExact',
+        ),
+        sql<boolean>`LOWER(f_unaccent(coalesce(pages.title, ''))) LIKE ${likePattern} ESCAPE '\\'`.as(
+          'titleSub',
+        ),
+        // 1-based position of the first text match (0 = no text match).
+        sql<number>`strpos(LOWER(f_unaccent(coalesce(pages.text_content, ''))), ${needle})`.as(
+          'textMatchPos',
+        ),
+        // FTS secondary signal (0 when the tsquery is empty).
+        hasTsQuery
+          ? sql<number>`ts_rank(pages.tsv, to_tsquery('english', f_unaccent(${tsQuery})))`.as(
+              'ftsRank',
+            )
+          : sql<number>`0`.as('ftsRank'),
+        // Windowed snippet, computed entirely in SQL. Priority:
+        //  1. window around the first text match;
+        //  2. otherwise (titleOnly: no snippet; else) a leading window of the
+        //     page text (title-only hit);
+        //  3. otherwise an extended ts_headline for pure-FTS hits.
+        //
+        // #443 snippet-position fix: the match position (`strpos`) is computed in
+        // the LOWER(f_unaccent(...)) space, but f_unaccent is NOT length-
+        // preserving (ß→ss, æ→ae, …→..., ½→ 1/2, full-width forms), so slicing
+        // the ORIGINAL text at that position was misaligned — a single expanding
+        // char before the match shifted the window (or ran it past end → empty).
+        // We now slice from the SAME LOWER(f_unaccent(...)) string so position
+        // and slice share one coordinate space. DELIBERATE trade-off: the snippet
+        // loses original case/diacritics — acceptable for an agent-facing snippet
+        // (position accuracy over original-glyph fidelity). The ts_headline branch
+        // matches over the ORIGINAL text itself, so it is unaffected and kept as-is.
+        searchParams.titleOnly
+          ? sql<string>`''`.as('snippet')
+          : sql<string>`
+          coalesce(
+            case
+              when strpos(LOWER(f_unaccent(coalesce(pages.text_content, ''))), ${needle}) > 0
+                then substring(
+                  LOWER(f_unaccent(coalesce(pages.text_content, '')))
+                  from greatest(1, strpos(LOWER(f_unaccent(coalesce(pages.text_content, ''))), ${needle}) - ${N_BEFORE})
+                  for ${SNIPPET_LEN}
+                )
+              when coalesce(pages.text_content, '') <> ''
+                then substring(LOWER(f_unaccent(pages.text_content)) from 1 for 300)
+              ${
+                hasTsQuery
+                  ? sql`else ts_headline('english', coalesce(pages.text_content, ''), to_tsquery('english', f_unaccent(${tsQuery})), 'MinWords=25, MaxWords=40, MaxFragments=3')`
+                  : sql``
+              }
+            end,
+            ''
+          )
+        `.as('snippet'),
+      ])
+      .where('pages.deletedAt', 'is', null)
+      .where('pages.spaceId', 'in', spaceIds);
+
+    if (descendantIds) {
+      candidates = candidates.where('pages.id', 'in', descendantIds);
+    }
+
+    // Match predicate: title substring OR (unless titleOnly) text substring OR
+    // (unless titleOnly) FTS. The substring branch runs even when the tsquery is
+    // empty — that is the dotted/numeric-token case the FTS path misses.
+    //
+    // #443 dead-index fix: these two LIKE predicates MUST match the GIN trgm
+    // index expressions EXACTLY for Postgres to use them. The indexes are on the
+    // coalesce-FREE expressions `LOWER(f_unaccent(title))` (#348's
+    // idx_pages_title_trgm) and `LOWER(f_unaccent(text_content))` (this PR's
+    // idx_pages_text_content_trgm). A `coalesce(col,'')` wrapper here would make
+    // the query expression differ from the index expression and force a Seq Scan
+    // on pages for every lookup. Dropping coalesce is SEMANTICALLY EQUIVALENT:
+    // `NULL LIKE '%q%'` is NULL (falsy), so a NULL title/text simply doesn't
+    // match — exactly as an empty string wouldn't match `%q%`.
+    candidates = candidates.where((eb) => {
+      const ors = [
+        eb(
+          sql`LOWER(f_unaccent(pages.title))`,
+          'like',
+          sql`${likePattern} ESCAPE '\\'`,
+        ),
+      ];
+      if (!searchParams.titleOnly) {
+        ors.push(
+          eb(
+            sql`LOWER(f_unaccent(pages.text_content))`,
+            'like',
+            sql`${likePattern} ESCAPE '\\'`,
+          ),
+        );
+        if (hasTsQuery) {
+          ors.push(
+            sql<boolean>`pages.tsv @@ to_tsquery('english', f_unaccent(${tsQuery}))` as any,
+          );
+        }
+      }
+      return eb.or(ors);
+    });
+
+    // Pull a generous candidate set (before permission filtering + limit).
+    // Cap it so a pathological match set cannot blow up memory; 200 >> limit
+    // (max 50) leaves ample headroom for the post-permission truncation.
+    //
+    // #443 cap-ordering fix: the 200-cap MUST be deterministic and relevance-
+    // biased. Without an ORDER BY, Postgres returns an ARBITRARY 200 rows, so on
+    // a broad match set (common word / short substring) a strong TITLE_EXACT hit
+    // could be among the dropped rows while 200 low-tier TEXT hits fill the cap.
+    // We order by the SAME SQL tier proxies the Node ranker uses — title-exact,
+    // then title-substring, then fts-rank (nulls last), then earliest text-match
+    // position — so the cap keeps the strongest candidates. The Node-side final
+    // tier sort + slice(0, limit) below still runs and stays authoritative; this
+    // ORDER BY only decides WHICH candidates survive the 200-cap.
+    // NB: a BARE integer literal in ORDER BY is read by Postgres as an ordinal
+    // column position (`ORDER BY 0` → "position 0 is not in select list"), so the
+    // no-tsquery fallback is `0::float`, not `0`.
+    const ftsRankExpr = hasTsQuery
+      ? sql`ts_rank(pages.tsv, to_tsquery('english', f_unaccent(${tsQuery})))`
+      : sql`0::float`;
+    const candidatesCapped = candidates
+      // Raw-SQL ORDER BY expressions: pass the full `<expr> <dir>` as ONE arg
+      // (the two-arg form treats a raw-SQL second arg as an ORDER BY position).
+      .orderBy(
+        sql`(LOWER(f_unaccent(coalesce(pages.title, ''))) = ${needle}) desc`,
+      )
+      .orderBy(
+        sql`(LOWER(f_unaccent(coalesce(pages.title, ''))) LIKE ${likePattern} ESCAPE '\\') desc`,
+      )
+      .orderBy(sql`${ftsRankExpr} desc nulls last`)
+      // Earlier text match first; strpos returns 0 for "no match", which would
+      // sort BEFORE a real (>=1) position under plain ASC, so push 0 to the end.
+      .orderBy(
+        sql`case when strpos(LOWER(f_unaccent(coalesce(pages.text_content, ''))), ${needle}) = 0 then 2147483647 else strpos(LOWER(f_unaccent(coalesce(pages.text_content, ''))), ${needle}) end asc`,
+      );
+
+    let rows: any[] = await candidatesCapped.limit(200).execute();
+
+    if (rows.length === 0) {
+      return { items: [] };
+    }
+
+    // --- Permissions BEFORE limit. --------------------------------------------
+    // Apply the existing page-level post-filter to the MERGED set, then rank and
+    // only THEN truncate to `limit` — never lose the permission filter.
+    if (opts.userId) {
+      const accessibleIds =
+        await this.pagePermissionRepo.filterAccessiblePageIds({
+          pageIds: rows.map((r) => r.id),
+          userId: opts.userId,
+          spaceId: searchParams.spaceId,
+          workspaceId: opts.workspaceId,
+        });
+      const accessibleSet = new Set(accessibleIds);
+      rows = rows.filter((r) => accessibleSet.has(r.id));
+    }
+
+    if (rows.length === 0) {
+      return { items: [] };
+    }
+
+    // --- Tiered ranking + dedup. ----------------------------------------------
+    // Rows are already unique by id (single pages scan), so no cross-branch
+    // dedup is needed here; the tier captures the strongest match reason.
+    const ranked = rows.map((r) => {
+      let tier: SearchLookupTier;
+      let secondary: number;
+      if (r.titleExact) {
+        tier = SearchLookupTier.TITLE_EXACT;
+        secondary = Number(r.ftsRank) || 0;
+      } else if (r.titleSub) {
+        tier = SearchLookupTier.TITLE_SUBSTRING;
+        secondary = Number(r.ftsRank) || 0;
+      } else {
+        tier = SearchLookupTier.TEXT;
+        // Prefer earlier text matches; map position → closeness in (0, 1].
+        const pos = Number(r.textMatchPos) || 0;
+        secondary =
+          pos > 0 ? 1 / (1 + (pos - 1) / 100) : Number(r.ftsRank) || 0;
+      }
+      return { row: r, tier, score: computeLookupScore({ tier, secondary }) };
+    });
+
+    ranked.sort((a, b) => b.score - a.score);
+    const top = ranked.slice(0, limit);
+
+    // --- Batch ancestor path (ONE recursive CTE, not N+1). --------------------
+    const pathById = await this.buildAncestorPaths(top.map((t) => t.row.id));
+
+    const items: SearchLookupResponseDto[] = top.map((t) => ({
+      id: t.row.id,
+      slugId: t.row.slugId,
+      title: t.row.title,
+      parentPageId: t.row.parentPageId ?? null,
+      path: pathById.get(t.row.id) ?? [],
+      snippet: (t.row.snippet ?? '')
+        .replace(/\r\n|\r|\n/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim(),
+      score: t.score,
+    }));
+
+    return { items };
+  }
+
+  /**
+   * Batch ancestor-titles helper (#443): ONE recursive CTE seeded with ALL hit
+   * ids, walking UP parentPageId. Returns a map hitId → ancestor titles ordered
+   * root → direct parent (the hit's own title is excluded). Root pages map to
+   * an empty array. Avoids the N+1 of a per-page breadcrumb call.
+   */
+  private async buildAncestorPaths(
+    hitIds: string[],
+  ): Promise<Map<string, string[]>> {
+    const result = new Map<string, string[]>();
+    if (hitIds.length === 0) return result;
+
+    // ancestry(hit_id, page_id, title, parent_page_id, depth): seed one row per
+    // hit at depth 0 (the hit itself), then walk to parents (increasing depth).
+    const rows = await this.db
+      .withRecursive('ancestry', (db) =>
+        db
+          .selectFrom('pages')
+          .select([
+            'pages.id as hitId',
+            'pages.id as pageId',
+            'pages.title as title',
+            'pages.parentPageId as parentPageId',
+            sql<number>`0`.as('depth'),
+          ])
+          .where('pages.id', 'in', hitIds)
+          .unionAll((exp) =>
+            exp
+              .selectFrom('pages as p')
+              .innerJoin('ancestry as a', 'p.id', 'a.parentPageId')
+              .select([
+                'a.hitId as hitId',
+                'p.id as pageId',
+                'p.title as title',
+                'p.parentPageId as parentPageId',
+                sql<number>`a.depth + 1`.as('depth'),
+              ]),
+          ),
+      )
+      .selectFrom('ancestry')
+      .select(['hitId', 'title', 'depth'])
+      // depth 0 is the hit itself — excluded from the path.
+      .where('depth', '>', 0)
+      .orderBy('hitId')
+      // Larger depth = closer to the space root. Ordering DESC gives
+      // root → parent once collected.
+      .orderBy('depth', 'desc')
+      .execute();
+
+    for (const r of rows as any[]) {
+      const list = result.get(r.hitId) ?? [];
+      list.push(r.title);
+      result.set(r.hitId, list);
+    }
+    return result;
+  }
+
   async searchSuggestions(
     suggestion: SearchSuggestionDTO,
     userId: string,

apps/server/src/core/share/share-alias.controller.spec.ts

@@ -133,6 +133,9 @@ describe('ShareAliasController authz gates', () => {
         creatorId: 'u-1',
         alias: 'promo',
         confirmReassign: true,
+        // The requesting user is forwarded so setAlias can gate the reassign
+        // 409 title disclosure on target-page view permission (#495).
+        user,
       });
       expect(result).toEqual({ id: 'alias-1' });
     });

apps/server/src/core/share/share-alias.controller.ts

@@ -79,6 +79,9 @@ export class ShareAliasController {
       creatorId: user.id,
       alias: dto.alias,
       confirmReassign: dto.confirmReassign,
+      // Gates whether the reassign 409 may reveal the current target's title
+      // (view-permission check on that page) — see setAlias (#495).
+      user,
     });
   }
 

apps/server/src/core/share/share-alias.service.spec.ts

@@ -1,4 +1,8 @@
-import { BadRequestException, ConflictException } from '@nestjs/common';
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+} from '@nestjs/common';
 import { NoResultError } from 'kysely';
 import { ShareAliasService } from './share-alias.service';
 
@@ -7,6 +11,8 @@ import { ShareAliasService } from './share-alias.service';
  * 409 reassign guard, uniqueness-race handling, availability probe, and the
  * request-time readable-target resolution (which re-runs the share boundary).
  */
+const USER = { id: 'u-1' } as any;
+
 describe('ShareAliasService', () => {
   // Sentinel handed to repo calls so tests can assert they ran inside the tx.
   const trx = { __trx: true };
@@ -27,6 +33,10 @@ describe('ShareAliasService', () => {
       resolveReadableSharePage: jest.fn(),
       isSharingAllowed: jest.fn(),
     };
+    // Default: the requester CAN view the target page (validateCanView resolves),
+    // so the reassign 409 may disclose its title. Tests override to reject to
+    // assert the no-leak path.
+    const pageAccessService = { validateCanView: jest.fn().mockResolvedValue(undefined) };
     // Fake kysely db: only .transaction().execute(cb) is used by setAlias.
     const db = {
       transaction: jest.fn(() => ({
@@ -37,9 +47,10 @@ describe('ShareAliasService', () => {
       shareAliasRepo as any,
       pageRepo as any,
       shareService as any,
+      pageAccessService as any,
       db as any,
     );
-    return { service, shareAliasRepo, pageRepo, shareService, db };
+    return { service, shareAliasRepo, pageRepo, shareService, pageAccessService, db };
   }
 
   describe('setAlias', () => {
@@ -50,6 +61,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'A', // too short + uppercase
         }),
       ).rejects.toBeInstanceOf(BadRequestException);
@@ -66,6 +78,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: '  My Page ',
       });
 
@@ -114,6 +127,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'ted',
       });
 
@@ -144,6 +158,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'foo',
       });
 
@@ -179,6 +194,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'new',
       });
 
@@ -190,30 +206,77 @@ describe('ShareAliasService', () => {
       );
     });
 
-    it('throws 409 with current target when name is taken and not confirmed', async () => {
-      const { service, shareAliasRepo, pageRepo } = makeService();
+    it('throws 409 with the target TITLE (never its id) when the requester CAN view it', async () => {
+      const { service, shareAliasRepo, pageRepo, pageAccessService } =
+        makeService();
       shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
         id: 'a-1',
         alias: 'foo',
         pageId: 'p-other',
       });
       pageRepo.findById.mockResolvedValue({ id: 'p-other', title: 'Other' });
+      pageAccessService.validateCanView.mockResolvedValue(undefined); // can view
 
       try {
         await service.setAlias({
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
       } catch (err) {
         expect(err).toBeInstanceOf(ConflictException);
-        expect((err as ConflictException).getResponse()).toMatchObject({
+        const body = (err as ConflictException).getResponse();
+        expect(body).toMatchObject({
           code: 'ALIAS_REASSIGN_REQUIRED',
-          currentPageId: 'p-other',
           currentPageTitle: 'Other',
         });
+        // SECURITY (#495): the page id is NEVER disclosed, even to a viewer.
+        expect(body).not.toHaveProperty('currentPageId');
+        expect(pageAccessService.validateCanView).toHaveBeenCalledWith(
+          expect.objectContaining({ id: 'p-other' }),
+          USER,
+        );
+      }
+      expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
+    });
+
+    it('throws 409 WITHOUT the title or id when the requester CANNOT view the target (#495)', async () => {
+      const { service, shareAliasRepo, pageRepo, pageAccessService } =
+        makeService();
+      shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
+        id: 'a-1',
+        alias: 'foo',
+        pageId: 'p-secret',
+      });
+      pageRepo.findById.mockResolvedValue({ id: 'p-secret', title: 'Secret' });
+      // No view permission on the target page -> validateCanView throws.
+      pageAccessService.validateCanView.mockRejectedValue(
+        new ForbiddenException(),
+      );
+
+      try {
+        await service.setAlias({
+          workspaceId: 'ws-1',
+          pageId: 'p-1',
+          creatorId: 'u-1',
+          user: USER,
+          alias: 'foo',
+        });
+        fail('expected ConflictException');
+      } catch (err) {
+        expect(err).toBeInstanceOf(ConflictException);
+        const body = (err as ConflictException).getResponse() as Record<
+          string,
+          unknown
+        >;
+        expect(body).toMatchObject({ code: 'ALIAS_REASSIGN_REQUIRED' });
+        // The enumeration hole: neither the id nor the title of a page the
+        // requester cannot see may leak.
+        expect(body).not.toHaveProperty('currentPageId');
+        expect(body.currentPageTitle ?? null).toBeNull();
       }
       expect(shareAliasRepo.updatePageId).not.toHaveBeenCalled();
     });
@@ -231,6 +294,7 @@ describe('ShareAliasService', () => {
         workspaceId: 'ws-1',
         pageId: 'p-1',
         creatorId: 'u-1',
+        user: USER,
         alias: 'foo',
         confirmReassign: true,
       });
@@ -269,6 +333,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -294,6 +359,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -317,6 +383,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -346,6 +413,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         });
         fail('expected ConflictException');
@@ -375,6 +443,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
           confirmReassign: true,
         });
@@ -406,6 +475,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'ted',
         });
         fail('expected ConflictException');
@@ -428,6 +498,7 @@ describe('ShareAliasService', () => {
           workspaceId: 'ws-1',
           pageId: 'p-1',
           creatorId: 'u-1',
+          user: USER,
           alias: 'foo',
         }),
       ).rejects.toBeInstanceOf(BadRequestException);
@@ -450,18 +521,22 @@ describe('ShareAliasService', () => {
         alias: 'free-name',
         valid: true,
         available: true,
-        currentPageId: null,
       });
+      // SECURITY (#495): the availability probe must NOT leak any page id.
+      expect(res).not.toHaveProperty('currentPageId');
     });
 
-    it('reports taken with the current target page', async () => {
+    it('reports taken WITHOUT leaking the current target page id (#495)', async () => {
       const { service, shareAliasRepo } = makeService();
       shareAliasRepo.findByAliasAndWorkspace.mockResolvedValue({
         id: 'a-1',
         pageId: 'p-9',
       });
       const res = await service.checkAvailability('taken', 'ws-1');
-      expect(res).toMatchObject({ available: false, currentPageId: 'p-9' });
+      expect(res).toMatchObject({ available: false });
+      // The row exists (available:false) but its pageId is never returned — an
+      // authenticated member cannot map an alias name to a page id it can't view.
+      expect(res).not.toHaveProperty('currentPageId');
     });
   });
 

apps/server/src/core/share/share-alias.service.ts

@@ -7,7 +7,8 @@ import {
 import { ShareAliasRepo } from '@docmost/db/repos/share-alias/share-alias.repo';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { ShareService } from './share.service';
-import { Page, ShareAlias } from '@docmost/db/types/entity.types';
+import { PageAccessService } from '../page/page-access/page-access.service';
+import { Page, ShareAlias, User } from '@docmost/db/types/entity.types';
 import { isValidShareAlias, normalizeShareAlias } from './share-alias.util';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
@@ -43,6 +44,7 @@ export class ShareAliasService {
     private readonly shareAliasRepo: ShareAliasRepo,
     private readonly pageRepo: PageRepo,
     private readonly shareService: ShareService,
+    private readonly pageAccessService: PageAccessService,
     @InjectKysely() private readonly db: KyselyDB,
   ) {}
 
@@ -55,9 +57,13 @@ export class ShareAliasService {
    *     `/l/<old>` link survives
    *   - name already points at pageId    -> no-op (idempotent)
    *   - name points at ANOTHER page      -> the "swap". Without confirmReassign
-   *     we throw 409 carrying the current target so the client can confirm;
-   *     with it we UPDATE the single row's page_id (every /l/<alias> link
-   *     follows the 302 to the new page instantly — no stale cache).
+   *     we throw 409 so the client can confirm. SECURITY (#495): the 409 reveals
+   *     the current target's title ONLY when `user` may VIEW that page, and never
+   *     its id — otherwise any member with one editable+shared page could iterate
+   *     alias names with confirmReassign=false and map them to (id, title) of
+   *     pages they cannot see. With confirmReassign we UPDATE the single row's
+   *     page_id (every /l/<alias> link follows the 302 to the new page instantly
+   *     — no stale cache).
    *
    * To keep the invariant self-healing we DELETE every other alias row still
    * pointing at this page (a legacy duplicate, or the target page's own former
@@ -77,8 +83,12 @@ export class ShareAliasService {
     creatorId: string;
     alias: string;
     confirmReassign?: boolean;
+    // The requesting user — used ONLY to gate whether the reassign 409 may reveal
+    // the current target page's title (view-permission check). Not an authz gate
+    // for the write itself (the controller already validated edit on `pageId`).
+    user: User;
   }): Promise<ShareAlias> {
-    const { workspaceId, pageId, creatorId, confirmReassign } = opts;
+    const { workspaceId, pageId, creatorId, confirmReassign, user } = opts;
     const alias = normalizeShareAlias(opts.alias);
     if (!isValidShareAlias(alias)) {
       throw new BadRequestException(
@@ -97,14 +107,30 @@ export class ShareAliasService {
         // The name is occupied by a DIFFERENT (or dangling) target page.
         if (byName && byName.pageId !== pageId) {
           if (!confirmReassign) {
+            // SECURITY (#495): only disclose the current target's TITLE, and only
+            // when the requester may VIEW that page. Never disclose its id (the
+            // client's confirm-reassign UX doesn't use it, and it is an enumerable
+            // identity). A member with one editable+shared page must NOT be able to
+            // iterate alias names and map them to (id, title) of pages they cannot
+            // see. When view is denied (or the alias is dangling) the 409 is the
+            // bare "occupied" fact — the client still shows a generic confirm modal.
             const currentPage = byName.pageId
               ? await this.pageRepo.findById(byName.pageId)
               : null;
+            let currentPageTitle: string | null = null;
+            if (currentPage) {
+              try {
+                await this.pageAccessService.validateCanView(currentPage, user);
+                currentPageTitle = currentPage.title ?? null;
+              } catch {
+                // No view permission on the target -> do not reveal its title.
+                currentPageTitle = null;
+              }
+            }
             throw new ConflictException({
               message: 'Alias already in use',
               code: 'ALIAS_REASSIGN_REQUIRED',
-              currentPageId: byName.pageId,
-              currentPageTitle: currentPage?.title ?? null,
+              currentPageTitle,
             });
           }
           // Confirmed swap. ORDER MATTERS: the partial unique index on
@@ -223,21 +249,27 @@ export class ShareAliasService {
     alias: string;
     valid: boolean;
     available: boolean;
-    currentPageId: string | null;
   }> {
     const alias = normalizeShareAlias(rawAlias);
     if (!isValidShareAlias(alias)) {
-      return { alias, valid: false, available: false, currentPageId: null };
+      return { alias, valid: false, available: false };
     }
     const existing = await this.shareAliasRepo.findByAliasAndWorkspace(
       alias,
       workspaceId,
     );
+    // SECURITY (#495): return ONLY the boolean availability. The previous shape
+    // leaked `currentPageId` — the id of whatever page the alias already targets —
+    // to ANY authenticated workspace member, with no view-permission check on that
+    // page. An attacker could enumerate alias names and map them to page ids they
+    // have no access to. The taken/free bit is all the "is this address free"
+    // probe needs. The reassign flow (setAlias 409) may surface the target's
+    // TITLE, but only behind a `validateCanView` on that page (see setAlias); it
+    // never returns the page id.
     return {
       alias,
       valid: true,
       available: !existing,
-      currentPageId: existing?.pageId ?? null,
     };
   }
 

apps/server/src/core/telemetry/client-metrics.constants.ts

@@ -24,6 +24,54 @@ export const ALLOWED_RATINGS = new Set<string>([
   'poor',
 ]);
 
+// The ONLY route labels accepted. The endpoint is anonymous, so an un-checked
+// `route` is a free-text write surface (arbitrary high-cardinality strings /
+// injected text into the metrics table). The client only ever sends a label from
+// a finite template dictionary (`templateRoute`), so we drop anything not in it.
+//
+// PARITY: this MUST mirror `KNOWN_ROUTE_TEMPLATES` in the client's
+// `apps/client/src/lib/telemetry/route-template.ts` (the canonical source). A
+// drift means legit client routes get dropped — keep the two in lockstep; the
+// client self-consistency test asserts `templateRoute` only emits these values.
+export const ALLOWED_ROUTE_TEMPLATES = new Set<string>([
+  '/',
+  'other',
+  // Static routes.
+  '/home',
+  '/spaces',
+  '/favorites',
+  '/login',
+  '/forgot-password',
+  '/password-reset',
+  '/setup/register',
+  '/settings/account/profile',
+  '/settings/account/preferences',
+  '/settings/workspace',
+  '/settings/ai',
+  '/settings/members',
+  '/settings/groups',
+  '/settings/spaces',
+  '/settings/sharing',
+  // Dynamic templates (slugs/ids are already collapsed to `:param`).
+  '/share/:shareId/p/:slug',
+  '/share/p/:slug',
+  '/share/:shareId',
+  '/p/:slug',
+  '/s/:space/p/:slug',
+  '/s/:space/trash',
+  '/s/:space',
+  '/labels/:label',
+  '/invites/:invitationId',
+  '/settings/groups/:groupId',
+]);
+
+// `attr` is a web-vitals attribution TARGET: a CSS-selector-ish string (an
+// element path like `html>body>div#app>button.cta`), never free prose. Constrain
+// it to a conservative CSS-selector charset so the anonymous endpoint cannot be
+// used to write arbitrary text / PII / markup into the metrics table. A value
+// containing anything outside this set is DROPPED (-> null); the event is kept.
+export const ATTR_ALLOWED_CHARSET = /^[A-Za-z0-9#.\-_> :()[\]="'*+~,]+$/;
+
 // Max events accepted per batch; the rest are ignored.
 export const MAX_EVENTS_PER_BATCH = 50;
 
@@ -77,14 +125,20 @@ export function sanitizeVitalEvent(
       ? e.rating
       : null;
 
+  // route: accept ONLY a known template label (dictionary check), else drop to
+  // null. The length cap stays as a cheap pre-guard before the Set lookup.
   let route: string | null = null;
   if (typeof e.route === 'string' && e.route.length > 0) {
-    route = e.route.slice(0, MAX_ROUTE_LENGTH);
+    const candidate = e.route.slice(0, MAX_ROUTE_LENGTH);
+    route = ALLOWED_ROUTE_TEMPLATES.has(candidate) ? candidate : null;
   }
 
+  // attr: truncate, then accept ONLY if it is a CSS-selector-shaped string
+  // (charset whitelist); anything with characters outside the set is dropped.
   let attr: string | null = null;
   if (typeof e.attr === 'string' && e.attr.length > 0) {
-    attr = e.attr.slice(0, MAX_ATTR_LENGTH);
+    const candidate = e.attr.slice(0, MAX_ATTR_LENGTH);
+    attr = ATTR_ALLOWED_CHARSET.test(candidate) ? candidate : null;
   }
 
   let docSize: number | null = null;