Merge remote-tracking branch 'gitea/develop' into feat/481-version-coherence

docs(reload-guard): align header/docstring wording to the window model (#481 review F2 consistency)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-12 05:36:59 +03:00 · 2026-07-12 05:36:58 +03:00 · 2026-07-12 05:32:33 +03:00 · 2026-07-12 05:16:51 +03:00 · 2026-07-12 05:16:47 +03:00 · 2026-07-12 05:08:57 +03:00
54 changed files with 3064 additions and 336 deletions
@@ -226,6 +226,13 @@ jobs:
      - name: Build mcp
        run: pnpm --filter @docmost/mcp build

+      # apps/server imports @docmost/token-estimate at runtime (history-budget.ts,
+      # #490); its dist/ is gitignored and `test:e2e` type-checks + runs the code,
+      # so build it here or tsc fails with TS2307 Cannot find module
+      # '@docmost/token-estimate' (mirrors the editor-ext / mcp build steps above).
+      - name: Build token-estimate
+        run: pnpm --filter @docmost/token-estimate build
+
      - name: Run migrations
        run: pnpm --filter ./apps/server migration:latest

@@ -159,6 +159,14 @@ jobs:
      - name: Build prosemirror-markdown
        run: pnpm --filter @docmost/prosemirror-markdown build

+      # @docmost/token-estimate is a shared workspace package the client vitest
+      # suite resolves via its dist build (main: ./dist/index.js); dist/ is
+      # gitignored and `pnpm -r test` does NOT honour nx `dependsOn: ^build`, so
+      # build it before the recursive test run or the client suite fails with
+      # "Failed to resolve import '@docmost/token-estimate'" (#490).
+      - name: Build token-estimate
+        run: pnpm --filter @docmost/token-estimate build
+
      - name: Run unit tests
        run: pnpm -r test

@@ -463,6 +463,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - 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`.
+- The build also emits `client/dist/version.json` (`{"version": …}`) from a small `vite.config.ts` plugin using the **same** `appVersion` that feeds `define.APP_VERSION`, so the file and the baked-in bundle version are identical by construction. The server reads it at startup (`ws.gateway.ts` via `readClientBuildVersion`/`resolveClientDistPath`) and announces it to each socket on connect (`app-version` event) so a tab left open across a redeploy can guard-reload before hitting a stale chunk (version-coherence). No runtime env / Dockerfile change — the file already ships in `client/dist`; missing/empty file ⇒ feature inert.

 ## Conventions

@@ -135,6 +135,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  new resync path re-reads the live anchor so the suggestion applies against the
  current text, and orphaned anchors (whose marked run was deleted) are
  reconciled rather than left blocking. (#496)
+- **Save intentional page versions.** Press `Cmd/Ctrl+S` (or use the page menu)
+  to save a named version of a page. The history panel now distinguishes
+  intentional versions (a "Saved" / "Agent version" badge) from automatic
+  snapshots, dims autosaves, and offers an "Only versions" filter. Automatic
+  snapshots switched from a fixed interval to a trailing idle-flush with a
+  max-wait ceiling, and a boundary snapshot is pinned whenever the editing source
+  changes (e.g. a person's edits followed by the AI agent). (#370)
+- **Open tabs pick up a new deploy on their own.** After the server is
+  redeployed while a tab is left open for hours, the tab now learns the new
+  build version over the existing WebSocket (announced per-connect, so a natural
+  reconnect delivers it) and shows a "A new version is available" banner with an
+  Update button. To avoid dropping a half-written comment or form, the tab is
+  not reloaded when you merely switch away from it; instead it auto-reloads at
+  the next safe point — the next in-app navigation (or immediately if you click
+  Update) — before it can hit a stale lazy-loaded chunk. At most one automatic
+  reload happens per 5-minute window, shared with the existing chunk-load
+  recovery, so a permanent version skew degrades to the banner rather than a
+  reload loop while a second deploy in the same tab still recovers. When the
+  build carries no version info the feature stays inert. (#481)

 - **Place several images side by side in a row.** A new "Inline (side by
  side)" alignment mode in the image bubble menu renders consecutive inline
@@ -385,6 +404,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  `@docmost/token-estimate` package) so they can never diverge. Deferred-tool
  activation is also cached in the chat metadata to avoid re-resolving it each
  turn. (#490)
+- **Cyrillic (and any non-ASCII) draw.io labels no longer turn into mojibake
+  when a diagram is opened in the draw.io editor.** Agent-created diagrams
+  (`drawioCreate`) and Confluence-imported diagrams stored their model in the
+  SVG's `content=` attribute as base64; the draw.io editor decodes that via
+  Latin-1 `atob` (no UTF-8 step), so every non-ASCII char (e.g. `Старт-бит`,
+  `ё`, `—`) split into garbage and the editor's autosave then persisted the
+  corrupted model, breaking the page preview too. Both write paths
+  (`buildDrawioSvg`, the import service's `createDrawioSvg`) now write `content=`
+  as XML-entity-escaped mxfile XML — draw.io's own native form, decoded by the
+  DOM as UTF-8 — so labels open intact. The decoder reads both the new
+  entity-encoded form and the old base64 form, so existing diagrams still open.
+  *Healing pre-fix diagrams:* only a diagram that still holds its original
+  (correct-UTF-8) base64 — i.e. one not yet opened/autosaved in the draw.io
+  editor — can be repaired in place by `drawioGet` → `drawioUpdate` with the
+  same XML (rewrites the attachment in the new form); no migration script is
+  needed. A diagram that was already opened in the editor persisted the
+  mojibake at rest, so `drawioGet` reads the already-corrupted text and
+  `drawioUpdate` faithfully rewrites it — that text is lost and is not
+  recoverable by a rewrite. (#507)
 - **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
@@ -59,6 +59,14 @@ COPY --from=builder /app/packages/mcp/data /app/packages/mcp/data
 COPY --from=builder /app/packages/prosemirror-markdown/build /app/packages/prosemirror-markdown/build
 COPY --from=builder /app/packages/prosemirror-markdown/package.json /app/packages/prosemirror-markdown/package.json

+# apps/server imports @docmost/token-estimate (workspace:*) at runtime
+# (history-budget.ts, #490). tsc emits only dist/ and dist/ is gitignored, so the
+# prod install would resolve a broken workspace symlink and the server would die
+# with ERR_MODULE_NOT_FOUND on the first history-budget call. Ship the built
+# package + its manifest, mirroring prosemirror-markdown above.
+COPY --from=builder /app/packages/token-estimate/dist /app/packages/token-estimate/dist
+COPY --from=builder /app/packages/token-estimate/package.json /app/packages/token-estimate/package.json
+
 # Copy root package files
 COPY --from=builder /app/package.json /app/package.json
 COPY --from=builder /app/pnpm*.yaml /app/
@@ -1,4 +1,5 @@
 {
+  "A new version is available": "A new version is available",
  "Account": "Account",
  "Active": "Active",
  "Add": "Add",
@@ -1418,5 +1419,14 @@
  "The commented text changed since this suggestion was made; it was not applied.": "The commented text changed since this suggestion was made; it was not applied.",
  "Dismiss": "Dismiss",
  "Suggestion dismissed": "Suggestion dismissed",
-  "Failed to dismiss suggestion": "Failed to dismiss suggestion"
+  "Failed to dismiss suggestion": "Failed to dismiss suggestion",
+  "Save version": "Save version",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Version saved",
+  "Already saved as the latest version": "Already saved as the latest version",
+  "Agent version": "Agent version",
+  "Boundary": "Boundary",
+  "Autosave": "Autosave",
+  "Only versions": "Only versions",
+  "No saved versions yet.": "No saved versions yet."
 }
@@ -1,4 +1,5 @@
 {
+  "A new version is available": "Доступна новая версия",
  "Account": "Аккаунт",
  "Active": "Активный",
  "Add": "Добавить",
@@ -1433,5 +1434,14 @@
  "The commented text changed since this suggestion was made; it was not applied.": "Прокомментированный текст изменился после создания предложения; оно не было применено.",
  "Dismiss": "Не применять",
  "Suggestion dismissed": "Предложение отклонено",
-  "Failed to dismiss suggestion": "Не удалось отклонить предложение"
+  "Failed to dismiss suggestion": "Не удалось отклонить предложение",
+  "Save version": "Сохранить версию",
+  "Ctrl+S": "Ctrl+S",
+  "Version saved": "Версия сохранена",
+  "Already saved as the latest version": "Уже сохранено как последняя версия",
+  "Agent version": "Версия агента",
+  "Boundary": "Граница",
+  "Autosave": "Автосейв",
+  "Only versions": "Только версии",
+  "No saved versions yet.": "Пока нет сохранённых версий."
 }
@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isChunkLoadError, shouldAutoReload } from "./chunk-load-error-boundary";
+import { isChunkLoadError } from "./chunk-load-error-boundary";

 // The detector decides whether a caught render error is a stale-deploy chunk-404
 // (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
@@ -35,31 +35,3 @@ 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);
-  });
-});
@@ -1,26 +1,11 @@
 import { ReactNode } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { Button, Center, Stack, Text } from "@mantine/core";
-
-// 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;
-}
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  recordReloadBreadcrumb,
+} from "@/lib/reload-guard";

 // Heuristic detection of a failed dynamic import. Since the code-splitting work,
 // every route (plus Aside / AiChatWindow) is React.lazy: when a new deploy
@@ -39,24 +24,26 @@ export function isChunkLoadError(error: unknown): boolean {
  );
 }

-function handleError(error: unknown) {
+// Exported for tests: the reactive chunk-load reload decision, so the shared
+// window budget (invariant: ≤1 auto-reload per window across this path AND the
+// proactive version-coherence path) can be exercised against the real guard.
+export 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 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 {
-    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.
-    return;
-  }
+  // the new chunk manifest. Auto-reload at most once per window via the SHARED
+  // window-based reload guard (see @/lib/reload-guard — the same budget the
+  // proactive version-coherence path consumes, so a mismatch that arrives on
+  // both paths reloads at most once per window across BOTH). 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. If the shared budget is already
+  // spent this window, or the stamp write fails (storage unavailable), we return
+  // without reloading rather than risk a loop.
+  if (hasAutoReloaded()) return;
+  if (!markAutoReloaded()) return;
+  // Trace before the reload clears the console (same diagnostic breadcrumb the
+  // proactive version-coherence path writes, tagged with this path).
+  recordReloadBreadcrumb({ path: "chunk-boundary" });
  window.location.reload();
 }

@@ -3,11 +3,20 @@ import { atom } from "jotai";
 // import would drag the whole @tiptap/core engine into the eager graph of every
 // shell component that reads one of these atoms.
 import type { Editor } from "@tiptap/core";
+import type { HocuspocusProvider } from "@hocuspocus/provider";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import type { DictationUnavailableReason } from "@/features/dictation/dictation-status";

 export const pageEditorAtom = atom<Editor | null>(null);

+// #370 — the active page's collab provider, published by the page editor so the
+// header menu can emit the "save-version" stateless signal (Cmd+S / button).
+// Null when the page is read-only / collab isn't connected. A typed initial
+// value (rather than an explicit generic) keeps jotai's overload resolution on
+// the writable PrimitiveAtom branch.
+const initialCollabProvider: HocuspocusProvider | null = null;
+export const collabProviderAtom = atom(initialCollabProvider);
+
 export const titleEditorAtom = atom<Editor | null>(null);

 export const readOnlyEditorAtom = atom<Editor | null>(null);
@@ -31,11 +31,18 @@ import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
+  collabProviderAtom,
  currentPageEditModeAtom,
  dictationAvailabilityAtom,
  pageEditorAtom,
  yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms";
+import { notifications } from "@mantine/notifications";
+import {
+  VERSION_SAVED_MESSAGE_TYPE,
+  type VersionSavedMessage,
+  saveVersionPending,
+} from "@/features/page-history/version-messages";
 import { asideStateAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom";
 import {
  activeCommentIdAtom,
@@ -124,6 +131,7 @@ export default function PageEditor({

  const [currentUser] = useAtom(currentUserAtom);
  const [, setEditor] = useAtom(pageEditorAtom);
+  const setCollabProvider = useSetAtom(collabProviderAtom);
  const [, setAsideState] = useAtom(asideStateAtom);
  const [, setActiveCommentId] = useAtom(activeCommentIdAtom);
  const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
@@ -181,6 +189,24 @@ export default function PageEditor({
      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
        try {
          const message = JSON.parse(payload);
+          // #370 — a version was saved somewhere; live-refresh the history panel
+          // on every client. Only the client that pressed Save (tracked by the
+          // module-level flag) shows the confirmation toast.
+          if (message?.type === VERSION_SAVED_MESSAGE_TYPE) {
+            const versionMsg = message as VersionSavedMessage;
+            queryClient.invalidateQueries({
+              queryKey: ["page-history-list"],
+            });
+            if (saveVersionPending.current) {
+              saveVersionPending.current = false;
+              notifications.show({
+                message: versionMsg.alreadySaved
+                  ? t("Already saved as the latest version")
+                  : t("Version saved"),
+              });
+            }
+            return;
+          }
          if (message?.type !== "page.updated" || !message.updatedAt) return;
          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
          if (pageData) {
@@ -238,12 +264,16 @@ export default function PageEditor({

      local.on("synced", onLocalSyncedHandler);
      providersRef.current = { socket, local, remote };
+      // #370 — publish the provider so the header menu can emit save-version.
+      setCollabProvider(remote);
      setProvidersReady(true);
    } else {
+      setCollabProvider(providersRef.current.remote);
      setProvidersReady(true);
    }
    // Only destroy on final unmount
    return () => {
+      setCollabProvider(null);
      providersRef.current?.socket.destroy();
      providersRef.current?.remote.destroy();
      providersRef.current?.local.destroy();
@@ -1,4 +1,11 @@
-import { Text, Group, UnstyledButton, Avatar, Tooltip } from "@mantine/core";
+import {
+  Text,
+  Group,
+  UnstyledButton,
+  Avatar,
+  Tooltip,
+  Badge,
+} from "@mantine/core";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
 import { formattedDate } from "@/lib/time";
@@ -7,36 +14,59 @@ import clsx from "clsx";
 import { IPageHistory } from "@/features/page-history/types/page.types";
 import { memo, useCallback } from "react";
 import { useSetAtom } from "jotai";
+import { useTranslation } from "react-i18next";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";

 const MAX_VISIBLE_AVATARS = 5;

+/**
+ * #370 — map a snapshot's intentionality tier to its badge. `version: true`
+ * marks the intentional points (manual / agent); autosaves (boundary / idle /
+ * legacy null) are non-versions and get dimmed in the list.
+ */
+type HistoryKindMeta = { labelKey: string; color: string; version: boolean };
+export function historyKindMeta(kind?: string | null): HistoryKindMeta {
+  switch (kind) {
+    case "manual":
+      return { labelKey: "Saved", color: "blue", version: true };
+    case "agent":
+      return { labelKey: "Agent version", color: "violet", version: true };
+    case "boundary":
+      return { labelKey: "Boundary", color: "gray", version: false };
+    default: // "idle" | null | undefined (legacy autosave)
+      return { labelKey: "Autosave", color: "gray", version: false };
+  }
+}
+
 interface HistoryItemProps {
  historyItem: IPageHistory;
-  index: number;
-  onSelect: (id: string, index: number) => void;
-  onHover?: (id: string, index: number) => void;
+  // The previous snapshot for diff/restore is resolved by id from the FULL list
+  // in the parent (resolvePrevSnapshotId), so the item only needs to report its
+  // own id — never a list index (which would be the filtered-view index).
+  onSelect: (id: string) => void;
+  onHover?: (id: string) => void;
  onHoverEnd?: () => void;
  isActive: boolean;
 }

 const HistoryItem = memo(function HistoryItem({
  historyItem,
-  index,
  onSelect,
  onHover,
  onHoverEnd,
  isActive,
 }: HistoryItemProps) {
  const setHistoryModalOpen = useSetAtom(historyAtoms);
+  const { t } = useTranslation();
+  const kindMeta = historyKindMeta(historyItem.kind);

  const handleClick = useCallback(() => {
-    onSelect(historyItem.id, index);
-  }, [onSelect, historyItem.id, index]);
+    onSelect(historyItem.id);
+  }, [onSelect, historyItem.id]);

  const handleMouseEnter = useCallback(() => {
-    onHover?.(historyItem.id, index);
-  }, [onHover, historyItem.id, index]);
+    onHover?.(historyItem.id);
+  }, [onHover, historyItem.id]);

  const contributors = historyItem.contributors;
  const hasContributors = contributors && contributors.length > 0;
@@ -49,8 +79,20 @@ const HistoryItem = memo(function HistoryItem({
      onMouseEnter={handleMouseEnter}
      onMouseLeave={onHoverEnd}
      className={clsx(classes.history, { [classes.active]: isActive })}
+      // #370 — dim autosnapshots so intentional versions stand out.
+      style={{ opacity: kindMeta.version ? 1 : 0.55 }}
    >
-      <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+      <Group gap={6} wrap="nowrap" justify="space-between">
+        <Text size="sm">{formattedDate(new Date(historyItem.createdAt))}</Text>
+        <Badge
+          size="xs"
+          radius="sm"
+          variant={kindMeta.version ? "filled" : "light"}
+          color={kindMeta.color}
+        >
+          {t(kindMeta.labelKey)}
+        </Badge>
+      </Group>

      <Group gap={6} wrap="nowrap" mt={4}>
        {hasContributors ? (
@@ -2,14 +2,16 @@ import {
  usePageHistoryListQuery,
  prefetchPageHistory,
 } from "@/features/page-history/queries/page-history-query";
-import HistoryItem from "@/features/page-history/components/history-item";
+import HistoryItem, {
+  historyKindMeta,
+} from "@/features/page-history/components/history-item";
 import {
  activeHistoryIdAtom,
  activeHistoryPrevIdAtom,
  historyAtoms,
 } from "@/features/page-history/atoms/history-atoms";
 import { useAtom, useSetAtom } from "jotai";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
  Button,
  ScrollArea,
@@ -17,9 +19,12 @@ import {
  Divider,
  Loader,
  Center,
+  Switch,
+  Text,
 } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import { useHistoryRestore } from "@/features/page-history/hooks";
+import { resolvePrevSnapshotId } from "@/features/page-history/utils/resolve-prev-snapshot";

 const PREFETCH_DELAY_MS = 150;

@@ -47,6 +52,22 @@ function HistoryList({ pageId }: Props) {
    [pageHistoryData],
  );

+  // #370 — "only versions" filter: hide autosnapshots (idle/boundary/legacy
+  // null), keep only intentional points (manual/agent). Filtering is over the
+  // already-loaded pages; the diff/restore still targets the true previous
+  // snapshot, so items carry their index within the FULL list.
+  const [onlyVersions, setOnlyVersions] = useState(false);
+  // Reuse historyKindMeta().version — the SAME predicate the badge (HistoryItem)
+  // uses to mark intentional points — so the "Only versions" filter and the badge
+  // can never drift apart when a future intentional kind is added.
+  const visibleItems = useMemo(
+    () =>
+      onlyVersions
+        ? historyItems.filter((item) => historyKindMeta(item.kind).version)
+        : historyItems,
+    [historyItems, onlyVersions],
+  );
+
  const loadMoreRef = useRef<HTMLDivElement>(null);
  const prefetchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);

@@ -60,11 +81,13 @@ function HistoryList({ pageId }: Props) {
  }, []);

  const handleHover = useCallback(
-    (historyId: string, index: number) => {
+    (historyId: string) => {
      clearPrefetchTimeout();
      prefetchTimeoutRef.current = setTimeout(() => {
        prefetchPageHistory(historyId);
-        const prevId = historyItems[index + 1]?.id;
+        // The true previous snapshot in the FULL list (not the previous visible
+        // one under the "only versions" filter).
+        const prevId = resolvePrevSnapshotId(historyItems, historyId);
        if (prevId) {
          prefetchPageHistory(prevId);
        }
@@ -78,9 +101,11 @@ function HistoryList({ pageId }: Props) {
  }, [clearPrefetchTimeout]);

  const handleSelect = useCallback(
-    (id: string, index: number) => {
+    (id: string) => {
      setActiveHistoryId(id);
-      setActiveHistoryPrevId(historyItems[index + 1]?.id ?? "");
+      // Baseline = true previous snapshot in the FULL list, so the "only
+      // versions" filter never diffs/restores against the wrong item.
+      setActiveHistoryPrevId(resolvePrevSnapshotId(historyItems, id));
    },
    [historyItems, setActiveHistoryId, setActiveHistoryPrevId],
  );
@@ -128,12 +153,27 @@ function HistoryList({ pageId }: Props) {

  return (
    <div>
+      <Group px="xs" py={6} justify="flex-end">
+        <Switch
+          size="xs"
+          checked={onlyVersions}
+          onChange={(e) => setOnlyVersions(e.currentTarget.checked)}
+          label={t("Only versions")}
+        />
+      </Group>
+
      <ScrollArea h={620} w="100%" type="scroll" scrollbarSize={5}>
-        {historyItems.map((historyItem, index) => (
+        {onlyVersions && visibleItems.length === 0 && (
+          <Center py="md">
+            <Text size="sm" c="dimmed">
+              {t("No saved versions yet.")}
+            </Text>
+          </Center>
+        )}
+        {visibleItems.map((historyItem) => (
          <HistoryItem
            key={historyItem.id}
            historyItem={historyItem}
-            index={index}
            onSelect={handleSelect}
            onHover={handleHover}
            onHoverEnd={clearPrefetchTimeout}
@@ -24,6 +24,10 @@ export interface IPageHistory {
  updatedAt: string;
  lastUpdatedBy: IPageHistoryUser;
  contributors?: IPageHistoryUser[];
+  // #370 — intentionality tier: 'manual'/'agent' are versions (intentional
+  // points), 'idle'/'boundary' are autosnapshots; null/undefined = legacy
+  // autosave. Derived server-side, drives the history badge + "versions" filter.
+  kind?: "manual" | "agent" | "idle" | "boundary" | null;
  // Provenance markers copied off the page row when the snapshot was saved.
  // `'agent'` marks a version written by the AI agent; `lastUpdatedAiChatId`
  // (when present) deep-links to the chat that produced the edit.
@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { resolvePrevSnapshotId } from "./resolve-prev-snapshot";
+
+// #370 F4 — the risky client path: with the "only versions" filter active, diff
+// and restore must still baseline against the TRUE previous snapshot in the FULL
+// list, never the previous VISIBLE version (which would skip the autosnapshots
+// between two versions). These pin that the resolution is by FULL-list order.
+describe("resolvePrevSnapshotId", () => {
+  // Newest-first, as the history list stores it: a version, then two autosaves,
+  // then an older version.
+  const full = [
+    { id: "v2", kind: "manual" },
+    { id: "a2", kind: "idle" },
+    { id: "a1", kind: "boundary" },
+    { id: "v1", kind: "manual" },
+    { id: "a0", kind: null },
+  ];
+
+  it("returns the immediate FULL-list successor, not the previous visible version", () => {
+    // Selecting v2 while filtered to versions-only must baseline against a2 (the
+    // real chronological predecessor), NOT v1 (the previous visible version).
+    expect(resolvePrevSnapshotId(full, "v2")).toBe("a2");
+  });
+
+  it("resolves an autosnapshot's predecessor by full-list order", () => {
+    expect(resolvePrevSnapshotId(full, "a1")).toBe("v1");
+  });
+
+  it("returns '' for the oldest item (no predecessor)", () => {
+    expect(resolvePrevSnapshotId(full, "a0")).toBe("");
+  });
+
+  it("returns '' for an id not in the list", () => {
+    expect(resolvePrevSnapshotId(full, "missing")).toBe("");
+  });
+
+  it("does not depend on a filtered subset — same result whatever is visible", () => {
+    // The helper only ever sees the full list; a filtered view cannot change the
+    // baseline it computes.
+    expect(resolvePrevSnapshotId(full, "v1")).toBe("a0");
+  });
+});
@@ -0,0 +1,22 @@
+/**
+ * #370 — resolve the TRUE previous snapshot for a history item.
+ *
+ * The history panel can be filtered to "only versions" (manual/agent), but diff
+ * and restore must always compare against the immediately-preceding snapshot in
+ * the FULL, unfiltered list — NOT the previous VISIBLE item. Comparing against
+ * the previous visible version would silently skip the autosnapshots between two
+ * versions and diff/restore the wrong baseline.
+ *
+ * Given the full (newest-first) list and an item id, this returns the id of the
+ * item right after it in the full list (its chronological predecessor), or "" if
+ * it is the oldest / not found. Pure and list-order-preserving so it can be unit
+ * tested without mounting the component.
+ */
+export function resolvePrevSnapshotId(
+  fullItems: ReadonlyArray<{ id: string }>,
+  id: string,
+): string {
+  const index = fullItems.findIndex((item) => item.id === id);
+  if (index === -1) return "";
+  return fullItems[index + 1]?.id ?? "";
+}
@@ -0,0 +1,28 @@
+/**
+ * #370 — page-version stateless wire formats. Kept in one place so the client
+ * emitter (Save hotkey / button) and the client listener (page-editor) agree
+ * with the server (PersistenceExtension) on the message shapes.
+ */
+
+/** Client → server: "save a version now". The server derives the tier
+ * (manual/agent) from the signed connection actor, never from this payload. */
+export const SAVE_VERSION_MESSAGE_TYPE = "save-version";
+
+/** Server → all clients: a version was saved (or promoted / already existed). */
+export const VERSION_SAVED_MESSAGE_TYPE = "version.saved";
+
+export interface VersionSavedMessage {
+  type: typeof VERSION_SAVED_MESSAGE_TYPE;
+  historyId: string;
+  kind: "manual" | "agent";
+  /** True when the latest snapshot was already a manual version (a no-op save). */
+  alreadySaved: boolean;
+}
+
+/**
+ * Cross-component coordination flag so only the client that pressed Save shows
+ * the confirmation toast, while every other client silently refreshes its
+ * history panel on the broadcast. A module-level ref avoids stale-closure
+ * pitfalls in the editor's long-lived stateless handler.
+ */
+export const saveVersionPending = { current: false };
@@ -3,6 +3,7 @@ import {
  IconArrowRight,
  IconArrowsHorizontal,
  IconClockHour4,
+  IconDeviceFloppy,
  IconDots,
  IconEye,
  IconEyeOff,
@@ -17,7 +18,7 @@ import {
  IconTrash,
  IconWifiOff,
 } from "@tabler/icons-react";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import { useAsideTriggerProps } from "@/hooks/use-toggle-aside.tsx";
 import { useAtom, useAtomValue } from "jotai";
 import { historyAtoms } from "@/features/page-history/atoms/history-atoms.ts";
@@ -39,9 +40,14 @@ import { Trans, useTranslation } from "react-i18next";
 import ExportModal from "@/components/common/export-modal";
 import { convertProseMirrorToMarkdown } from "@docmost/prosemirror-markdown/browser";
 import {
+  collabProviderAtom,
  pageEditorAtom,
  yjsConnectionStatusAtom,
 } from "@/features/editor/atoms/editor-atoms.ts";
+import {
+  SAVE_VERSION_MESSAGE_TYPE,
+  saveVersionPending,
+} from "@/features/page-history/version-messages.ts";
 import { formattedDate } from "@/lib/time.ts";
 import { PageEditModeToggle } from "@/features/user/components/page-state-pref.tsx";
 import MovePageModal from "@/features/page/components/move-page-modal.tsx";
@@ -72,9 +78,34 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
  });
  const isDeleted = !!page?.deletedAt;
  const [workspace] = useAtom(workspaceAtom);
+  const collabProvider = useAtomValue(collabProviderAtom);
  // Community public-sharing entry point (replaces the removed EE PageShareModal)
  const workspaceSharingDisabled = workspace?.settings?.sharing?.disabled === true;

+  // #370 — explicit "save a version" (Cmd+S / Save button). One path for the
+  // human; the server derives the tier from the signed actor. Readers can't save
+  // (the button is hidden and the collab connection is read-only server-side).
+  const handleSaveVersion = useCallback(() => {
+    if (readOnly || !collabProvider) return;
+    // Flag this client as the initiator so only it shows the confirmation toast;
+    // a safety timeout clears it if no broadcast comes back (e.g. offline).
+    saveVersionPending.current = true;
+    window.setTimeout(() => {
+      saveVersionPending.current = false;
+    }, 5000);
+    collabProvider.sendStateless(
+      JSON.stringify({ type: SAVE_VERSION_MESSAGE_TYPE }),
+    );
+  }, [readOnly, collabProvider]);
+
+  // mod+S must also block the browser's "Save page" dialog. `triggerOnContent-
+  // Editable` + empty ignore-list so it fires while typing in the editor/title.
+  useHotkeys(
+    [["mod+S", handleSaveVersion, { preventDefault: true }]],
+    [],
+    true,
+  );
+
  useHotkeys(
    [
      [
@@ -133,15 +164,16 @@ export default function PageHeaderMenu({ readOnly }: PageHeaderMenuProps) {
        </ActionIcon>
      </Tooltip>

-      <PageActionMenu readOnly={readOnly} />
+      <PageActionMenu readOnly={readOnly} onSaveVersion={handleSaveVersion} />
    </>
  );
 }

 interface PageActionMenuProps {
  readOnly?: boolean;
+  onSaveVersion?: () => void;
 }
-function PageActionMenu({ readOnly }: PageActionMenuProps) {
+function PageActionMenu({ readOnly, onSaveVersion }: PageActionMenuProps) {
  const { t } = useTranslation();
  const [, setHistoryModalOpen] = useAtom(historyAtoms);
  const clipboard = useClipboard({ timeout: 500 });
@@ -303,6 +335,20 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
            </Group>
          </Menu.Item>

+          {!readOnly && (
+            <Menu.Item
+              leftSection={<IconDeviceFloppy size={16} />}
+              onClick={onSaveVersion}
+              rightSection={
+                <Text size="xs" c="dimmed">
+                  {t("Ctrl+S")}
+                </Text>
+              }
+            >
+              {t("Save version")}
+            </Menu.Item>
+          )}
+
          <Menu.Item
            leftSection={<IconHistory size={16} />}
            onClick={openHistoryModal}
@@ -281,10 +281,12 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
      setOpenTreeNodes((prev) => ({ ...prev, [id]: isOpen }));
      if (isOpen) {
        const node = treeModel.find(data, id) as SpaceTreeNode | null;
-        if (
-          node?.hasChildren &&
-          (!node.children || node.children.length === 0)
-        ) {
+        // Same "unloaded branch" predicate the realtime insert paths use
+        // (`isUnloadedBranch`) so the lazy-load gate and the realtime inserts
+        // (`insertByPosition` / `placeByPosition`) can never disagree about what
+        // counts as unloaded (#525). Note: local raw `insert` (DnD/create-page)
+        // does not yet route through it — see #525 follow-up.
+        if (treeModel.isUnloadedBranch(node)) {
          const fetched = await fetchAllAncestorChildren({
            pageId: id,
            spaceId: node.spaceId,
@@ -74,6 +74,48 @@ describe("treeModel.isDescendant", () => {
  });
 });

+// #525: the single "is this branch unloaded?" predicate shared by the lazy-load
+// gate and the insert paths. Unloaded == server says hasChildren but none are
+// present locally (canonical form `children: []`, also `undefined`). A parent
+// without hasChildren is genuinely empty, not unloaded.
+describe("treeModel.isUnloadedBranch", () => {
+  type PH = TreeNode<{ name: string; hasChildren?: boolean }>;
+  it("true for hasChildren + empty array (canonical unloaded form)", () => {
+    const n: PH = { id: "p", name: "P", hasChildren: true, children: [] };
+    expect(treeModel.isUnloadedBranch(n)).toBe(true);
+  });
+  it("true for hasChildren + undefined children", () => {
+    const n: PH = { id: "p", name: "P", hasChildren: true };
+    expect(treeModel.isUnloadedBranch(n)).toBe(true);
+  });
+  it("false for hasChildren + already-loaded children", () => {
+    const n: PH = {
+      id: "p",
+      name: "P",
+      hasChildren: true,
+      children: [{ id: "c", name: "C" }],
+    };
+    expect(treeModel.isUnloadedBranch(n)).toBe(false);
+  });
+  it("false for a genuinely-empty parent (no hasChildren)", () => {
+    expect(
+      treeModel.isUnloadedBranch({
+        id: "p",
+        name: "P",
+        hasChildren: false,
+        children: [],
+      } as PH),
+    ).toBe(false);
+    expect(
+      treeModel.isUnloadedBranch({ id: "p", name: "P" } as PH),
+    ).toBe(false);
+  });
+  it("false for null/undefined", () => {
+    expect(treeModel.isUnloadedBranch(null)).toBe(false);
+    expect(treeModel.isUnloadedBranch(undefined)).toBe(false);
+  });
+});
+
 describe("treeModel.visible", () => {
  it("returns only root nodes when no openIds", () => {
    const v = treeModel.visible(fixture, new Set());
@@ -197,43 +239,64 @@ describe("treeModel.insertByPosition", () => {
    ]);
  });

-  // #159 #1: inserting/moving a node under a parent whose children are NOT
-  // loaded (`children === undefined`, e.g. a collapsed page) must NOT materialize
-  // a partial `[node]` list — that would defeat the lazy-load gate and hide the
-  // parent's other real children. The node is left to be lazy-loaded; only
-  // `hasChildren` is flagged so the chevron appears.
-  it("does NOT materialize a child under an UNLOADED parent (children undefined)", () => {
-    type PH = TreeNode<{
-      name: string;
-      position?: string;
-      hasChildren?: boolean;
-    }>;
+  type PH = TreeNode<{
+    name: string;
+    position?: string;
+    hasChildren?: boolean;
+  }>;
+
+  // #159 #1 / #525: inserting/moving a node under an UNLOADED parent must NOT
+  // materialize a partial `[node]` list — that would defeat the lazy-load gate and
+  // hide the parent's other real children. The canonical unloaded form here is
+  // `children: []` + `hasChildren: true` (from `pageToTreeNode` /
+  // `pruneCollapsedChildren`), which the pre-#525 `=== undefined` guard MISSED.
+  // The node is left to be lazy-loaded; the chevron stays enabled.
+  it("does NOT materialize a child under an UNLOADED parent (children: [], hasChildren: true)", () => {
    const tree: PH[] = [
-      { id: "p", name: "P", position: "a0", hasChildren: false }, // children: undefined
+      { id: "p", name: "P", position: "a0", hasChildren: true, children: [] },
    ];
    const node: PH = { id: "x", name: "X", position: "a1" };
    const t = treeModel.insertByPosition(tree, "p", node);
    const parent = treeModel.find(t, "p");
    // The node was NOT inserted (children stay unloaded -> lazy-load fetches the
-    // full set, including this node, on expand).
-    expect(parent?.children).toBeUndefined();
+    // full set, including this node, on expand). MUTATION: the pre-#525 predicate
+    // `children === undefined` does not fire for `[]`, so it would insert `[x]`
+    // here and reredden this expectation.
+    expect(parent?.children).toEqual([]);
    expect(treeModel.find(t, "x")).toBeNull();
-    // ...but the chevron is enabled so the user can expand to load it.
+    // ...and the chevron stays enabled so the user can expand to load it.
    expect((parent as PH).hasChildren).toBe(true);
  });

-  it("DOES insert under a LOADED-but-empty parent (children: [])", () => {
-    type PH = TreeNode<{
-      name: string;
-      position?: string;
-      hasChildren?: boolean;
-    }>;
+  it("does NOT materialize a child under an UNLOADED parent (children undefined, hasChildren: true)", () => {
+    const tree: PH[] = [
+      { id: "p", name: "P", position: "a0", hasChildren: true }, // children: undefined
+    ];
+    const node: PH = { id: "x", name: "X", position: "a1" };
+    const t = treeModel.insertByPosition(tree, "p", node);
+    const parent = treeModel.find(t, "p");
+    expect(parent?.children).toBeUndefined();
+    expect(treeModel.find(t, "x")).toBeNull();
+    expect((parent as PH).hasChildren).toBe(true);
+  });
+
+  it("DOES insert under a genuinely-empty parent (children: [], hasChildren: false)", () => {
    const tree: PH[] = [
      { id: "p", name: "P", position: "a0", hasChildren: false, children: [] },
    ];
    const node: PH = { id: "x", name: "X", position: "a1" };
    const t = treeModel.insertByPosition(tree, "p", node);
-    // A loaded (empty) child list is complete, so the node IS inserted.
+    // No server children (`hasChildren: false`), so materializing the first child
+    // is correct — nothing is hidden.
+    expect(treeModel.find(t, "p")?.children?.map((n) => n.id)).toEqual(["x"]);
+  });
+
+  it("DOES insert under a genuinely-empty parent (children undefined, hasChildren: false)", () => {
+    const tree: PH[] = [
+      { id: "p", name: "P", position: "a0", hasChildren: false }, // children: undefined
+    ];
+    const node: PH = { id: "x", name: "X", position: "a1" };
+    const t = treeModel.insertByPosition(tree, "p", node);
    expect(treeModel.find(t, "p")?.children?.map((n) => n.id)).toEqual(["x"]);
  });

@@ -43,6 +43,26 @@ export const treeModel = {
    };
  },

+  // A branch is "unloaded" when the server says it HAS children (`hasChildren`)
+  // but none are present locally. The canonical unloaded form in this codebase
+  // is `children: []` (produced by `pageToTreeNode` and by `pruneCollapsedChildren`
+  // resetting collapsed branches), NOT `children: undefined` — so a predicate that
+  // only checks `=== undefined` misses the real case and materializes a misleading
+  // partial list (#525). This is the SINGLE source of truth for "should a
+  // fetch/materialize be deferred?", shared by the lazy-load gate (`handleToggle`)
+  // and the realtime insert paths (`insertByPosition` / `placeByPosition`), so they
+  // can never drift apart again. (The local raw `insert` primitive and its DnD/
+  // create-page callers do NOT yet route through this predicate — see #525
+  // follow-up.) A parent WITHOUT `hasChildren` is genuinely empty
+  // (no server children) — inserting its first child is correct, not deferred.
+  isUnloadedBranch<T extends object>(
+    node: TreeNode<T> | null | undefined,
+  ): boolean {
+    if (!node) return false;
+    const hasChildren = (node as { hasChildren?: boolean }).hasChildren === true;
+    return hasChildren && (node.children == null || node.children.length === 0);
+  },
+
  isDescendant<T extends object>(
    tree: TreeNode<T>[],
    ancestorId: string,
@@ -127,14 +147,15 @@ export const treeModel = {
    }
    const parent = treeModel.find(tree, parentId);
    // The parent is in the tree but its children have NOT been lazy-loaded yet
-    // (`children === undefined`, distinct from a loaded-but-empty `[]`). Inserting
+    // (`hasChildren` set + children absent/empty — see `isUnloadedBranch`; the
+    // canonical unloaded form is `children: []`, NOT just `undefined`). Inserting
    // here would MATERIALIZE a misleading partial child list (`[node]`) that
    // defeats the lazy-load gate — which fetches only when children are
    // absent/empty — so the parent's OTHER real children would never load and the
    // moved/added node would be the only one shown (a silent data loss, #159 #1).
    // Instead, leave the children unloaded and just flag `hasChildren` so the
    // chevron appears; expanding fetches the FULL set (including this node).
-    if (parent && parent.children === undefined) {
+    if (parent && treeModel.isUnloadedBranch(parent)) {
      return treeModel.update(
        tree,
        parentId,
@@ -0,0 +1,195 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, act, cleanup } from "@testing-library/react";
+import { MemoryRouter, useNavigate } from "react-router-dom";
+
+// Mocks for the dirty shell's side-effecting collaborators.
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+vi.mock("@/i18n.ts", () => ({ default: { t: (k: string) => k } }));
+vi.mock("@/lib/reload-guard", () => ({
+  hasAutoReloaded: vi.fn(() => false),
+  markAutoReloaded: vi.fn(() => true),
+  recordReloadBreadcrumb: vi.fn(),
+  takeReloadBreadcrumb: vi.fn(() => null),
+}));
+
+import { notifications } from "@mantine/notifications";
+import { hasAutoReloaded, markAutoReloaded } from "@/lib/reload-guard";
+import {
+  triggerGuardedReload,
+  useVersionReloadOnNavigation,
+  __resetGuardedReloadForTests,
+} from "./guarded-reload";
+
+const show = notifications.show as unknown as ReturnType<typeof vi.fn>;
+const mockHasAutoReloaded = hasAutoReloaded as unknown as ReturnType<
+  typeof vi.fn
+>;
+const mockMarkAutoReloaded = markAutoReloaded as unknown as ReturnType<
+  typeof vi.fn
+>;
+
+let reload: ReturnType<typeof vi.fn>;
+let visibility: DocumentVisibilityState;
+
+// Test harness mounted inside a router: it installs the navigation hook and
+// exposes `navigate` so a test can drive an in-app router navigation.
+let doNavigate: (to: string) => void;
+function Harness() {
+  useVersionReloadOnNavigation();
+  const navigate = useNavigate();
+  doNavigate = navigate;
+  return null;
+}
+
+function mountHarness() {
+  render(
+    <MemoryRouter initialEntries={["/start"]}>
+      <Harness />
+    </MemoryRouter>,
+  );
+}
+
+function navigateTo(path: string) {
+  act(() => {
+    doNavigate(path);
+  });
+}
+
+beforeEach(() => {
+  __resetGuardedReloadForTests();
+  vi.clearAllMocks();
+  mockHasAutoReloaded.mockReturnValue(false);
+  mockMarkAutoReloaded.mockReturnValue(true);
+
+  vi.stubGlobal("APP_VERSION", "test-A");
+
+  reload = vi.fn();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: { reload },
+  });
+
+  visibility = "visible";
+  Object.defineProperty(document, "visibilityState", {
+    configurable: true,
+    get: () => visibility,
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("triggerGuardedReload (variant C)", () => {
+  it("noop when versions match: no banner, no reload", () => {
+    triggerGuardedReload("test-A");
+    expect(show).not.toHaveBeenCalled();
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("noop when the server version is empty (fail-safe)", () => {
+    triggerGuardedReload("");
+    triggerGuardedReload(undefined);
+    expect(show).not.toHaveBeenCalled();
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("real mismatch shows the banner but does NOT reload immediately", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(show).toHaveBeenCalledTimes(1);
+    expect(show.mock.calls[0][0]).toMatchObject({
+      id: "app-version-reload",
+      autoClose: false,
+      withCloseButton: true,
+    });
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("reloads EXACTLY ONCE on the first in-app navigation after a mismatch", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(reload).not.toHaveBeenCalled();
+
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+
+    // A second navigation must NOT reload again (one-shot was consumed).
+    navigateTo("/again");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT reload on a 2nd mismatch after the first was armed/consumed (one-shot)", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+
+    // Another app-version mismatch arrives (reconnect): must not re-arm.
+    triggerGuardedReload("test-C");
+    navigateTo("/again");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT reload merely from the tab going to the background", () => {
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(reload).not.toHaveBeenCalled();
+
+    visibility = "hidden";
+    act(() => {
+      document.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("a hidden-at-receipt tab is also NOT reloaded immediately (variant C uniform); reloads on next navigation", () => {
+    visibility = "hidden";
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(reload).not.toHaveBeenCalled();
+    expect(show).toHaveBeenCalledTimes(1);
+
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("the banner's Update button reloads immediately", () => {
+    triggerGuardedReload("test-B");
+    const message = show.mock.calls[0][0].message as {
+      props: { onClick: () => void };
+    };
+    message.props.onClick();
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("banner-only (auto-reload already spent): banner, never auto-reload on navigation", () => {
+    mockHasAutoReloaded.mockReturnValue(true);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    expect(show).toHaveBeenCalledTimes(1);
+
+    navigateTo("/next");
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("does NOT reload when the flag write fails; falls back to the banner", () => {
+    mockMarkAutoReloaded.mockReturnValue(false);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).not.toHaveBeenCalled();
+    // performAutoReload falls back to showing the banner (initial + fallback).
+    expect(show).toHaveBeenCalled();
+  });
+
+  it("is idempotent within a tab-load: repeated emits do not stack banners", () => {
+    triggerGuardedReload("test-B");
+    triggerGuardedReload("test-B");
+    triggerGuardedReload("test-C");
+    expect(show).toHaveBeenCalledTimes(1);
+  });
+});
@@ -0,0 +1,188 @@
+import { useEffect, useRef } from "react";
+import { useLocation } from "react-router-dom";
+import { Button } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import i18n from "@/i18n.ts";
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  recordReloadBreadcrumb,
+  takeReloadBreadcrumb,
+} from "@/lib/reload-guard";
+import { decideVersionAction } from "@/features/user/version-coherence";
+
+// Dirty shell around the pure `decideVersionAction`: it reads globals
+// (APP_VERSION), touches sessionStorage via the shared reload-guard, drives the
+// Mantine notification, and arms the router-navigation reload hook. Kept
+// separate from the pure module so the decision stays unit-testable without a
+// DOM.
+
+// One fixed id so repeated app-version signals (e.g. every reconnect) update a
+// single banner instead of stacking a new one each time.
+const BANNER_ID = "app-version-reload";
+
+// Module-level idempotency for the current tab-load: once a mismatch has been
+// handled we don't re-arm the navigation reload or re-show the banner on
+// subsequent app-version emits.
+let handled = false;
+
+// Variant C: on a real mismatch we do NOT reload the tab when it merely goes to
+// the background (that would silently drop a half-written comment/form). Instead
+// we arm a one-shot reload for the NEXT in-app router navigation — a point where
+// the user is already leaving the current page, so an in-app navigation would
+// discard that unsaved component-state anyway and the reload adds no extra loss.
+let pendingNavReload = false;
+
+// Remembered from the last detected mismatch for the pre-reload breadcrumb and
+// the (already-visible) banner.
+let lastServerVersion = "";
+let lastClientVersion = "";
+
+// Read the build version baked into THIS bundle. The `typeof` guard avoids a
+// ReferenceError where the `APP_VERSION` global is absent (e.g. under vitest,
+// where Vite's `define` did not run) — an unknown client version makes the
+// pure decision no-op (fail-safe).
+function readClientVersion(): string {
+  return (typeof APP_VERSION !== "undefined" ? APP_VERSION : "").trim();
+}
+
+// Perform the actual reload — but only after the shared one-shot flag is
+// persisted. If the write fails (storage unavailable) we must NOT reload
+// (mirrors the reactive chunk-load boundary's `catch → return`), and fall back
+// to the manual banner so the user can still recover.
+function performAutoReload(): void {
+  if (!markAutoReloaded()) {
+    showReloadBanner();
+    return;
+  }
+  // Trace right before the reload (which clears the console): a persistent
+  // breadcrumb + a log line so the auto-reload is observable in a field report.
+  recordReloadBreadcrumb({
+    path: "proactive",
+    serverVersion: lastServerVersion,
+    clientVersion: lastClientVersion,
+  });
+  console.warn(
+    `[version-coherence] auto-reloading: client=${lastClientVersion} -> server=${lastServerVersion}`,
+  );
+  window.location.reload();
+}
+
+function showReloadBanner(): void {
+  notifications.show({
+    id: BANNER_ID,
+    title: i18n.t("A new version is available"),
+    message: (
+      <Button size="xs" mt="xs" onClick={() => performAutoReload()}>
+        {i18n.t("Update")}
+      </Button>
+    ),
+    autoClose: false,
+    withCloseButton: true,
+  });
+}
+
+/**
+ * Handle a server `app-version` announcement: compare it to this bundle's
+ * version and, on a real mismatch, show the banner and arm a guarded reload for
+ * the next in-app navigation (variant C).
+ *
+ * - real mismatch (window budget available) → banner + arm navigation reload.
+ *   The banner's "Update" button reloads immediately (same shared window guard).
+ *   The tab is NOT reloaded on visibility change.
+ * - auto-reload already used this window / storage error → banner only (no arm),
+ *   so there is at most one automatic reload per RELOAD_WINDOW_MS window (loop
+ *   safety).
+ * - in sync / unknown version → noop (fail-safe).
+ */
+export function triggerGuardedReload(
+  rawServerVersion: string | undefined | null,
+): void {
+  const serverVersion = (rawServerVersion ?? "").trim();
+  const clientVersion = readClientVersion();
+
+  // A storage read error surfaces as autoReloadUsed=true → fail toward NOT
+  // reloading (banner only).
+  const autoReloadUsed = hasAutoReloaded();
+
+  const action = decideVersionAction({
+    serverVersion,
+    clientVersion,
+    autoReloadUsed,
+  });
+  if (action === "noop") return;
+
+  // Idempotent per tab-load: don't re-arm or re-stack the banner across repeated
+  // emits (reconnects) once we've already acted.
+  if (handled) return;
+  handled = true;
+
+  lastServerVersion = serverVersion;
+  lastClientVersion = clientVersion;
+
+  if (action === "banner") {
+    // Entered banner-only (permanent skew, node oscillation, or the window's
+    // auto-reload budget already spent). Log for diagnosability; show the banner.
+    console.warn(
+      `[version-coherence] server=${serverVersion} client=${clientVersion}: ` +
+        "auto-reload budget already spent this window — showing manual banner",
+    );
+    showReloadBanner();
+    return;
+  }
+
+  // action === "reload" (variant C): show the banner and defer the auto-reload
+  // to the next in-app navigation instead of reloading now / on visibility.
+  showReloadBanner();
+  pendingNavReload = true;
+}
+
+/**
+ * Consume the armed one-shot navigation reload, if any. Called by
+ * `useVersionReloadOnNavigation` on each in-app router navigation.
+ */
+export function consumeNavigationReload(): void {
+  if (!pendingNavReload) return;
+  pendingNavReload = false;
+  performAutoReload();
+}
+
+/**
+ * Hook (mounted inside the Router) that fires the armed one-shot reload on the
+ * NEXT in-app router navigation after a version mismatch. Skips the initial
+ * render so it only reacts to real navigations, not the first location.
+ */
+export function useVersionReloadOnNavigation(): void {
+  const location = useLocation();
+  const firstRender = useRef(true);
+  useEffect(() => {
+    if (firstRender.current) {
+      firstRender.current = false;
+      return;
+    }
+    consumeNavigationReload();
+  }, [location.key]);
+}
+
+/**
+ * Surface (log once) the breadcrumb left by an auto-reload in the previous page
+ * load — the reload cleared the console, so this makes a "tab reloaded itself"
+ * report diagnosable. Call once on app startup.
+ */
+export function surfacePreviousReloadBreadcrumb(): void {
+  const crumb = takeReloadBreadcrumb();
+  if (!crumb) return;
+  console.info(
+    `[version-coherence] previous auto-reload: path=${crumb.path} ` +
+      `client=${crumb.clientVersion ?? ""} -> server=${crumb.serverVersion ?? ""} ` +
+      `at=${new Date(crumb.at).toISOString()}`,
+  );
+}
+
+// Test-only: reset module-level latches between cases.
+export function __resetGuardedReloadForTests(): void {
+  handled = false;
+  pendingNavReload = false;
+  lastServerVersion = "";
+  lastClientVersion = "";
+}
@@ -0,0 +1,171 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { render, act, cleanup } from "@testing-library/react";
+import { MemoryRouter, useNavigate } from "react-router-dom";
+
+// Integration test for the SHARED, window-based auto-reload budget (invariant a):
+// the reactive chunk-load boundary and the proactive version-coherence path both
+// route through the REAL @/lib/reload-guard, so at most one automatic reload
+// happens per RELOAD_WINDOW_MS across BOTH paths combined. Only the two paths'
+// side-effecting collaborators are mocked — the reload guard is intentionally
+// REAL so this exercises the actual shared sessionStorage budget.
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn() },
+}));
+vi.mock("@/i18n.ts", () => ({ default: { t: (k: string) => k } }));
+
+import { handleError } from "@/components/chunk-load-error-boundary";
+import {
+  triggerGuardedReload,
+  useVersionReloadOnNavigation,
+  __resetGuardedReloadForTests,
+} from "./guarded-reload";
+import { RELOAD_WINDOW_MS } from "@/lib/reload-guard";
+
+const CHUNK_ERROR = { name: "ChunkLoadError", message: "boom" };
+const T0 = 1_000_000_000_000;
+
+let reload: ReturnType<typeof vi.fn>;
+let nowMock: ReturnType<typeof vi.spyOn>;
+
+// Harness mounted inside a router: installs the navigation hook and exposes
+// `navigate` so a test can drive an in-app router navigation (the point where the
+// proactive path fires its armed reload).
+let doNavigate: (to: string) => void;
+function Harness() {
+  useVersionReloadOnNavigation();
+  doNavigate = useNavigate();
+  return null;
+}
+function mountHarness() {
+  render(
+    <MemoryRouter initialEntries={["/start"]}>
+      <Harness />
+    </MemoryRouter>,
+  );
+}
+function navigateTo(path: string) {
+  act(() => {
+    doNavigate(path);
+  });
+}
+function setNow(t: number) {
+  nowMock.mockReturnValue(t);
+}
+
+beforeEach(() => {
+  sessionStorage.clear();
+  __resetGuardedReloadForTests();
+  vi.clearAllMocks();
+  nowMock = vi.spyOn(Date, "now").mockReturnValue(T0);
+  vi.stubGlobal("APP_VERSION", "test-A");
+  reload = vi.fn();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: { reload },
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  sessionStorage.clear();
+});
+
+describe("shared window-based reload budget (invariant a)", () => {
+  it("a chunk-load reload spends the budget: a version-coherence mismatch within the window shows the banner but does NOT reload", () => {
+    // Path 1 (reactive): a stale-chunk 404 auto-reloads once and stamps the window.
+    handleError(CHUNK_ERROR);
+    expect(reload).toHaveBeenCalledTimes(1);
+    reload.mockClear();
+
+    // Path 2 (proactive), 1 min later — still inside the window. The shared budget
+    // is spent, so the version mismatch degrades to the banner and never reloads.
+    setNow(T0 + 60_000);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("a version-coherence reload spends the SAME budget: a chunk-load error within the window does NOT reload", () => {
+    // Path 2 (proactive) first: real mismatch → arm → fire on navigation.
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+    reload.mockClear();
+
+    // Path 1 (reactive), 2 min later — inside the window. Budget already spent by
+    // the proactive path, so the stale-chunk error must NOT trigger a second reload.
+    setNow(T0 + 2 * 60_000);
+    handleError(CHUNK_ERROR);
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("recovers after the window: a reload strictly older than the window is allowed again (second deploy)", () => {
+    // First auto-reload (reactive) stamps the window.
+    handleError(CHUNK_ERROR);
+    expect(reload).toHaveBeenCalledTimes(1);
+    reload.mockClear();
+
+    // A second deploy arrives after the window has fully elapsed → the proactive
+    // path is allowed to reload again (window, not a permanent one-shot).
+    __resetGuardedReloadForTests();
+    setNow(T0 + RELOAD_WINDOW_MS + 1);
+    mountHarness();
+    triggerGuardedReload("test-B");
+    navigateTo("/next");
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("reactive path fails closed when storage READS but cannot WRITE (quota / Safari private): no unguarded reload", () => {
+    // getItem→null makes hasAutoReloaded() report the budget as available, so
+    // handleError passes the first guard and reaches `if (!markAutoReloaded())
+    // return;`. setItem throws → the stamp cannot stick, so markAutoReloaded()
+    // returns false and that guard MUST bail — otherwise the reactive path would
+    // reload on every stale-chunk error with no persisted budget (an unguarded
+    // loop). This is the asymmetric gap: the proactive path's equivalent is
+    // covered by guarded-reload.test.tsx "does NOT reload when the flag write
+    // fails".
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("quota exceeded");
+      },
+      removeItem: () => {},
+      clear: () => {},
+    });
+    try {
+      handleError(CHUNK_ERROR);
+      expect(reload).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("sessionStorage unavailable: neither path performs an unguarded reload", () => {
+    // The real guard fails toward NOT reloading when storage throws.
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => {
+        throw new Error("storage disabled");
+      },
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+      removeItem: () => {},
+      clear: () => {},
+    });
+    try {
+      handleError(CHUNK_ERROR);
+      expect(reload).not.toHaveBeenCalled();
+
+      mountHarness();
+      triggerGuardedReload("test-B");
+      navigateTo("/next");
+      expect(reload).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
@@ -13,6 +13,12 @@ import { useCollabToken } from "@/features/auth/queries/auth-query.tsx";
 import { Error404 } from "@/components/ui/error-404.tsx";
 import { queryClient } from "@/main.tsx";
 import { makeConnectHandler } from "@/features/user/connect-resync.ts";
+import {
+  triggerGuardedReload,
+  useVersionReloadOnNavigation,
+  surfacePreviousReloadBreadcrumb,
+} from "@/features/user/guarded-reload.tsx";
+import type { AppVersionSocketPayload } from "@/features/user/version-coherence.ts";

 export function UserProvider({ children }: React.PropsWithChildren) {
  const [, setCurrentUser] = useAtom(currentUserAtom);
@@ -22,6 +28,16 @@ export function UserProvider({ children }: React.PropsWithChildren) {
  // fetch collab token on load
  const { data: collab } = useCollabToken();

+  // version-coherence: fire the armed one-shot reload on the next in-app
+  // navigation (variant C — a safe point, not on tab backgrounding).
+  useVersionReloadOnNavigation();
+
+  // Surface any breadcrumb left by an auto-reload in the previous page load
+  // (the reload cleared the console) so a field report stays diagnosable.
+  useEffect(() => {
+    surfacePreviousReloadBreadcrumb();
+  }, []);
+
  useEffect(() => {
    if (isLoading || isError) {
      return;
@@ -47,6 +63,16 @@ export function UserProvider({ children }: React.PropsWithChildren) {
      handleConnect();
    });

+    // Register the version-coherence listener SYNCHRONOUSLY, before the socket
+    // connects: the server emits `app-version` immediately in handleConnection,
+    // so a listener attached after connect would miss it on a fast localhost
+    // connect. On a version mismatch the client shows a banner and defers the
+    // auto-reload to the next in-app navigation (variant C — avoids reloading a
+    // backgrounded tab that may hold unsaved input) before it hits a stale chunk.
+    newSocket.on("app-version", (payload?: AppVersionSocketPayload) => {
+      triggerGuardedReload(payload?.version);
+    });
+
    return () => {
      console.log("ws disconnected");
      newSocket.disconnect();
@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { decideVersionAction } from "./version-coherence";
+
+describe("decideVersionAction", () => {
+  it("noop when the server version is empty (fail-safe)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "",
+        clientVersion: "v1",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("noop when the client version is empty (fail-safe)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("noop when versions are equal (in sync)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "v1",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("reload on a real mismatch the first time this session", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "test-B",
+        clientVersion: "test-A",
+        autoReloadUsed: false,
+      }),
+    ).toBe("reload");
+  });
+
+  it("banner on a mismatch once the session auto-reload is spent", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "test-B",
+        clientVersion: "test-A",
+        autoReloadUsed: true,
+      }),
+    ).toBe("banner");
+  });
+
+  it("equal versions stay noop even if auto-reload was already used", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "v1",
+        autoReloadUsed: true,
+      }),
+    ).toBe("noop");
+  });
+});
@@ -0,0 +1,32 @@
+// Payload of the per-connect `app-version` socket.io event announced by the
+// server (ws.gateway.ts) after a successful auth. A dedicated event — NOT a
+// member of the room-scoped `WebSocketEvent` union (which is discriminated by
+// `operation`), so it never touches use-query-subscription.
+export type AppVersionSocketPayload = { version: string };
+
+/**
+ * Pure decision for the version-coherence guard.
+ *
+ * All inputs are injected (no globals, no side effects) so it is unit-testable
+ * without a DOM or the build-time `APP_VERSION` global (undefined under vitest).
+ *
+ * - `autoReloadUsed` = an automatic reload has already happened within the
+ *   current ~5-min window, so we must not auto-reload again (loop safety,
+ *   shared window budget with the reactive chunk-load boundary).
+ *
+ * Returns:
+ * - "noop"   — do nothing (unknown version on either side, or already in sync).
+ * - "banner" — show the manual "update available" banner only (no auto-reload).
+ * - "reload" — real first-time mismatch: eligible for a guarded auto-reload.
+ */
+export function decideVersionAction(args: {
+  serverVersion: string;
+  clientVersion: string;
+  autoReloadUsed: boolean;
+}): "reload" | "banner" | "noop" {
+  const { serverVersion, clientVersion, autoReloadUsed } = args;
+  if (!serverVersion || !clientVersion) return "noop"; // fail-safe: unknown version → never act
+  if (serverVersion === clientVersion) return "noop"; // in sync
+  if (autoReloadUsed) return "banner"; // one auto-reload per RELOAD_WINDOW_MS window already spent
+  return "reload"; // real mismatch, window budget available
+}
@@ -82,17 +82,19 @@ describe("applyMoveTreeNode", () => {
    ]);
  });

-  it("does NOT create a partial child list when the destination is loaded-but-collapsed (children unloaded) — keeps it lazy-loadable (#159)", () => {
-    // `dstCollapsed` is in the tree but its children were never lazy-loaded
-    // (children === undefined). The OLD behavior inserted `src` as the ONLY
-    // child ([src]), which defeated the lazy-load gate and HID the parent's
-    // other real children. Now the move leaves children unloaded (so expanding
-    // fetches the FULL set, including src) and just flags hasChildren.
+  it("does NOT create a partial child list when the destination is loaded-but-collapsed (children unloaded) — keeps it lazy-loadable (#159 #525)", () => {
+    // `dstCollapsed` is in the tree but its children were never lazy-loaded. The
+    // CANONICAL unloaded form here is `hasChildren: true` + `children: []` (from
+    // `pageToTreeNode` / `pruneCollapsedChildren`), NOT `children: undefined`.
+    // The pre-#525 predicate (`children === undefined`) missed this form and
+    // inserted `src` as the ONLY child ([src]), defeating the lazy-load gate and
+    // HIDING the parent's other real children. Now the move leaves children
+    // unloaded (so expanding fetches the FULL set, including src).
    const tree: SpaceTreeNode[] = [
      node("dstCollapsed", {
        position: "a0",
-        hasChildren: false,
-        children: undefined as unknown as SpaceTreeNode[],
+        hasChildren: true,
+        children: [],
      }),
      node("src", { position: "a9" }),
    ];
@@ -105,9 +107,10 @@ describe("applyMoveTreeNode", () => {
      pageData: {},
    });
    const dst = treeModel.find(next, "dstCollapsed");
-    // Children stay unloaded -> the lazy-load gate fetches the FULL set (incl.
-    // src) on expand, rather than showing a misleading partial [src] list.
-    expect(dst?.children).toBeUndefined();
+    // Children stay unloaded ([] not materialized to [src]) -> the lazy-load gate
+    // fetches the FULL set (incl. src) on expand. MUTATION: the pre-#525
+    // `=== undefined` predicate would insert [src] here and redden this.
+    expect(dst?.children).toEqual([]);
    expect(dst?.hasChildren).toBe(true);
    // src moved away from its old root slot (it lives under dstCollapsed
    // server-side and reappears when the parent is expanded/loaded).
@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  shouldAutoReload,
+  recordReloadBreadcrumb,
+  takeReloadBreadcrumb,
+  RELOAD_WINDOW_MS,
+} from "./reload-guard";
+
+// The shared budget is a single sessionStorage timestamp keyed here; both the
+// reactive chunk-load boundary and the proactive version-coherence path read and
+// stamp it, so at most one auto-reload happens per RELOAD_WINDOW_MS across BOTH.
+const RELOAD_AT_KEY = "chunk-reload-at";
+const NOW = 1_000_000_000_000;
+
+describe("reload-guard", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("hasAutoReloaded is false before any reload, true within the window after mark", () => {
+    expect(hasAutoReloaded(NOW)).toBe(false);
+    expect(markAutoReloaded(NOW)).toBe(true);
+    // Same key both paths share; stores the reload timestamp, not a flag.
+    expect(sessionStorage.getItem(RELOAD_AT_KEY)).toBe(String(NOW));
+    // Inside the window → budget spent → true (fall through to manual UI).
+    expect(hasAutoReloaded(NOW)).toBe(true);
+    expect(hasAutoReloaded(NOW + RELOAD_WINDOW_MS)).toBe(true);
+  });
+
+  it("hasAutoReloaded is false again once the window has elapsed (a later deploy recovers)", () => {
+    markAutoReloaded(NOW);
+    // Strictly older than the window → a new deploy's mismatch may reload again.
+    expect(hasAutoReloaded(NOW + RELOAD_WINDOW_MS + 1)).toBe(false);
+  });
+
+  it("hasAutoReloaded returns true when reading storage throws (fail toward not reloading)", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => {
+        throw new Error("storage disabled");
+      },
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+    });
+    try {
+      expect(hasAutoReloaded()).toBe(true);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("hasAutoReloaded treats an unparseable stored timestamp as never-reloaded", () => {
+    sessionStorage.setItem(RELOAD_AT_KEY, "not-a-number");
+    expect(hasAutoReloaded(NOW)).toBe(false);
+  });
+
+  it("markAutoReloaded returns false when writing storage throws", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+    });
+    try {
+      expect(markAutoReloaded()).toBe(false);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("records and then takes a breadcrumb once (cleared on read)", () => {
+    recordReloadBreadcrumb({
+      path: "proactive",
+      serverVersion: "test-B",
+      clientVersion: "test-A",
+    });
+    const crumb = takeReloadBreadcrumb();
+    expect(crumb).toMatchObject({
+      path: "proactive",
+      serverVersion: "test-B",
+      clientVersion: "test-A",
+    });
+    expect(typeof crumb?.at).toBe("number");
+    // Cleared on read → a second take returns null.
+    expect(takeReloadBreadcrumb()).toBeNull();
+  });
+
+  it("takeReloadBreadcrumb returns null when nothing was recorded", () => {
+    expect(takeReloadBreadcrumb()).toBeNull();
+  });
+
+  it("recordReloadBreadcrumb swallows a storage-write error (diagnostics only)", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+      removeItem: () => {},
+    });
+    try {
+      expect(() =>
+        recordReloadBreadcrumb({ path: "chunk-boundary" }),
+      ).not.toThrow();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+// The pure 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). Moved here from the chunk-load boundary now that it is the shared
+// guard both paths route through.
+describe("shouldAutoReload", () => {
+  const WINDOW = RELOAD_WINDOW_MS;
+
+  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);
+  });
+});
@@ -0,0 +1,121 @@
+// Shared, window-based auto-reload budget.
+//
+// Both auto-reload paths — the reactive chunk-load-error-boundary (recovers
+// AFTER a stale lazy chunk 404s) and the proactive version-coherence feature
+// (reloads BEFORE the tab hits a stale chunk) — go through these functions so
+// they share ONE window-scoped reload budget: at most a single automatic
+// reload per RELOAD_WINDOW_MS across BOTH paths. A window (rather than a
+// permanent one-shot flag) lets a SECOND deploy in the same tab's lifetime
+// recover too, while a permanent skew, node oscillation, or a genuinely-missing
+// chunk still degrades to a manual banner/UI after the first reload instead of
+// looping. When sessionStorage is unavailable every mismatch degrades to the
+// manual UI — no unguarded reload.
+
+// sessionStorage key holding the epoch-ms timestamp of the last automatic reload
+// (shared by both paths).
+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 / permanent skew) and falls through to the manual UI.
+export 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;
+}
+
+/**
+ * Has an automatic reload already happened within the current window (so the
+ * shared budget is spent right now)? Both paths check this before reloading; a
+ * `true` return means fall through to the manual banner/UI instead of reloading.
+ *
+ * A storage read error (private mode / disabled) is reported as `true` so the
+ * caller fails toward NOT reloading — an unguarded loop is worse than a stale
+ * tab the user can reload manually. Note a window (not a permanent flag): once
+ * the window elapses a later deploy's mismatch is allowed to reload again.
+ */
+export function hasAutoReloaded(now: number = Date.now()): boolean {
+  try {
+    const raw = sessionStorage.getItem(RELOAD_AT_KEY);
+    const lastReloadAt = raw === null ? null : Number.parseInt(raw, 10);
+    return !shouldAutoReload(now, lastReloadAt, RELOAD_WINDOW_MS);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Stamp the shared window as consumed now — record that an automatic reload is
+ * being performed within the current RELOAD_WINDOW_MS window.
+ *
+ * Returns whether the write succeeded. A `false` return (storage unavailable)
+ * means the caller MUST NOT reload — otherwise the stamp would never stick and
+ * the reload could loop.
+ */
+export function markAutoReloaded(now: number = Date.now()): boolean {
+  try {
+    sessionStorage.setItem(RELOAD_AT_KEY, String(now));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Diagnostic breadcrumb for an automatic reload. Written right before
+// window.location.reload() (which clears the console) and read back on the next
+// page load, so a "the tab reloaded itself / it's looping" field report is
+// diagnosable: which path fired (proactive version-coherence vs the reactive
+// chunk-load boundary) and which version pair triggered it. sessionStorage
+// survives a same-tab reload, unlike the console.
+const RELOAD_BREADCRUMB_KEY = "reload-breadcrumb";
+
+export type ReloadBreadcrumb = {
+  path: "proactive" | "chunk-boundary";
+  serverVersion?: string;
+  clientVersion?: string;
+  at: number;
+};
+
+/**
+ * Persist a best-effort breadcrumb just before an automatic reload. Failures
+ * (storage unavailable) are swallowed — this is diagnostics only and must never
+ * block or alter the reload decision.
+ */
+export function recordReloadBreadcrumb(
+  entry: Omit<ReloadBreadcrumb, "at">,
+): void {
+  try {
+    sessionStorage.setItem(
+      RELOAD_BREADCRUMB_KEY,
+      JSON.stringify({ ...entry, at: Date.now() }),
+    );
+  } catch {
+    // best-effort diagnostics only
+  }
+}
+
+/**
+ * Read and clear the breadcrumb left by an auto-reload in the previous page
+ * load. Cleared on read so it surfaces exactly once per reload.
+ */
+export function takeReloadBreadcrumb(): ReloadBreadcrumb | null {
+  try {
+    const raw = sessionStorage.getItem(RELOAD_BREADCRUMB_KEY);
+    if (!raw) return null;
+    sessionStorage.removeItem(RELOAD_BREADCRUMB_KEY);
+    return JSON.parse(raw) as ReloadBreadcrumb;
+  } catch {
+    return null;
+  }
+}
@@ -1,7 +1,8 @@
-import { defineConfig, loadEnv } from "vite";
+import { defineConfig, loadEnv, type Plugin } from "vite";
 import react from "@vitejs/plugin-react";
 import { compression } from "vite-plugin-compression2";
 import * as path from "path";
+import * as fs from "node:fs";
 import { execSync } from "node:child_process";

 const envPath = path.resolve(process.cwd(), "..", "..");
@@ -24,7 +25,32 @@ function resolveAppVersion(cwd: string): string {
  }
 }

+// Emit <outDir>/version.json = { "version": appVersion } so the server can read
+// the exact same build id the bundle was compiled with. The value is the SAME
+// `appVersion` fed into `define.APP_VERSION`, so version.json and the baked-in
+// global are identical by construction — the single source of truth (no
+// runtime-env second copy that could drift and cause a false version mismatch).
+function versionJsonPlugin(version: string): Plugin {
+  let outDir = "dist";
+  return {
+    name: "emit-version-json",
+    apply: "build",
+    configResolved(config) {
+      outDir = config.build.outDir;
+    },
+    writeBundle() {
+      const root = path.resolve(process.cwd(), outDir);
+      fs.mkdirSync(root, { recursive: true });
+      fs.writeFileSync(
+        path.join(root, "version.json"),
+        JSON.stringify({ version }),
+      );
+    },
+  };
+}
+
 export default defineConfig(({ mode }) => {
+  const appVersion = resolveAppVersion(envPath);
  const {
    APP_URL,
    FILE_UPLOAD_SIZE_LIMIT,
@@ -52,10 +78,11 @@ export default defineConfig(({ mode }) => {
        POSTHOG_HOST,
        POSTHOG_KEY,
      },
-      APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
+      APP_VERSION: JSON.stringify(appVersion),
    },
    plugins: [
      react(),
+      versionJsonPlugin(appVersion),
      // Emit .br and .gz next to every built asset so the server can serve the
      // precompressed copy (see @fastify/static preCompressed in static.module.ts).
      compression({
@@ -1,10 +1,36 @@
-export const HISTORY_INTERVAL = 5 * 60 * 1000;
-export const HISTORY_FAST_INTERVAL = 60 * 1000;
-export const HISTORY_FAST_THRESHOLD = 5 * 60 * 1000;
-
 // #348 — debounce window for the per-page RAG re-embed job. Repeated saves
 // within this window collapse to a single delayed job (coalesced by a stable
 // jobId), so active editing does not pile up expensive re-embeds (external API
 // + page_embeddings rewrite, concurrency 1). The worker reads the CURRENT page
 // state at run time, so the last content within the window wins.
 export const EMBED_DEBOUNCE_MS = 30 * 1000;
+
+/**
+ * #370 — page-history intentionality tiers. Domain of `page_history.kind`.
+ *   - 'manual' / 'agent'  → Tier 1 versions (intentional points)
+ *   - 'idle' / 'boundary' → Tier 0 autosnapshots (safety net)
+ * A legacy `null` kind is treated as an autosave.
+ */
+export type PageHistoryKind = 'manual' | 'agent' | 'idle' | 'boundary';
+
+/**
+ * #370 — trailing idle-flush windows. A page's pending idle snapshot is
+ * re-armed on every store and fires this long after edits go quiet, so a burst
+ * of edits collapses into a single autosnapshot instead of one-per-store. Human
+ * sessions are noisier and less risky, so they flush less often than the agent.
+ */
+export const IDLE_INTERVAL_USER = 60 * 60 * 1000; // 60m
+export const IDLE_INTERVAL_AGENT = 15 * 60 * 1000; // 15m
+
+/**
+ * #370 — max-wait ceiling for the idle flush. Pure trailing debounce starves the
+ * safety net: hocuspocus stores at least every ~45s, so a CONTINUOUS editing
+ * session would re-arm the trailing timer forever and never take an idle
+ * snapshot until edits finally go quiet (up to IDLE_INTERVAL_USER = 60m). This
+ * ceiling bounds the actual wait from the FIRST edit of a burst, so an idle
+ * snapshot fires at least this often during a long unbroken session — restoring
+ * a recovery point cadence closer to the old heuristic without one-per-store
+ * noise. Mirrors hocuspocus's own maxDebounce idea.
+ */
+export const IDLE_MAX_WAIT_USER = 10 * 60 * 1000; // 10m
+export const IDLE_MAX_WAIT_AGENT = 5 * 60 * 1000; // 5m
@@ -1,84 +1,93 @@
+import { computeHistoryJob, resolveSource } from './persistence.extension';
 import {
-  computeHistoryJob,
-  resolveSource,
-} from './persistence.extension';
-import {
-  HISTORY_FAST_INTERVAL,
-  HISTORY_FAST_THRESHOLD,
-  HISTORY_INTERVAL,
+  IDLE_INTERVAL_AGENT,
+  IDLE_INTERVAL_USER,
+  IDLE_MAX_WAIT_AGENT,
+  IDLE_MAX_WAIT_USER,
 } from '../constants';

-// A fixed clock + fixed createdAt make pageAge deterministic.
-const NOW = 1_700_000_000_000;
 const PAGE_ID = '550e8400-e29b-41d4-a716-446655440000';

-// Build a minimal page whose age (NOW - createdAt) is exactly `ageMs`.
-const pageAged = (ageMs: number) => ({
-  id: PAGE_ID,
-  createdAt: new Date(NOW - ageMs),
-});
+const page = { id: PAGE_ID };

-describe('computeHistoryJob', () => {
-  it('agent edit → delay MUST be 0 and job id is source-keyed', () => {
-    // INVARIANT (§15 H2 / persistence.extension): the agent delay MUST stay 0.
-    // The worker re-reads the page row at run time, so any non-zero delay risks
-    // snapshotting content a later human edit has already overwritten. This is
-    // the load-bearing assertion of this spec — do not relax it.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'agent', NOW);
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('agent edit on an OLD page is still delay 0 (age never applies to agents)', () => {
-    // Even when the page is far older than the fast threshold, the agent path
-    // must short-circuit to 0 — age-based debounce is a human-only concern.
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 60_000),
-      'agent',
-      NOW,
-    );
-    expect(delay).toBe(0);
-    expect(jobId).toBe(`${PAGE_ID}-agent`);
-  });
-
-  it('human edit on a YOUNG page (age < threshold) → fast interval, bare job id', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD - 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+describe('computeHistoryJob (#370 — shared trailing idle pipeline)', () => {
+  it('human edit → user idle window, bare page.id job', () => {
+    // Humans and the agent now share ONE idle job per page (jobId = page.id).
+    // The agent's old delay=0 fast path is GONE — intentional agent points now
+    // arrive via the explicit save-version signal, not a zero-delay snapshot.
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
    expect(jobId).toBe(PAGE_ID);
  });

-  it('human edit on an OLD page (age > threshold) → standard interval', () => {
-    const { jobId, delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD + 1),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent edit → agent idle window (shorter), still the bare page.id job', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'agent');
+    expect(delay).toBe(IDLE_INTERVAL_AGENT);
+    // No `-agent` suffix anymore: the agent joins the common idle pipeline.
    expect(jobId).toBe(PAGE_ID);
  });

-  it('boundary: pageAge EXACTLY === threshold takes the slow branch (the `<` is strict)', () => {
-    // Off-by-one guard: the condition is `pageAge < HISTORY_FAST_THRESHOLD`, so
-    // an age of exactly the threshold is NOT "fast" — it must use HISTORY_INTERVAL.
-    const { delay } = computeHistoryJob(
-      pageAged(HISTORY_FAST_THRESHOLD),
-      'user',
-      NOW,
-    );
-    expect(delay).toBe(HISTORY_INTERVAL);
+  it('agent flushes sooner than a human', () => {
+    expect(IDLE_INTERVAL_AGENT).toBeLessThan(IDLE_INTERVAL_USER);
  });

-  it('treats any non-"agent" source string as human', () => {
-    // resolveSource only ever yields 'agent' | 'user', but guard the contract:
-    // the agent branch keys strictly on === 'agent'.
-    const { jobId, delay } = computeHistoryJob(pageAged(0), 'user', NOW);
-    expect(delay).toBe(HISTORY_FAST_INTERVAL);
+  it('treats any non-"agent" source string as human (keys strictly on === agent)', () => {
+    const { jobId, delay } = computeHistoryJob(page, 'user');
+    expect(delay).toBe(IDLE_INTERVAL_USER);
    expect(jobId).toBe(PAGE_ID);
  });
+
+  // #370 review round-1 WARNING: the max-wait ceiling prevents autosnapshot
+  // starvation during a continuous editing session (the trailing timer would
+  // otherwise re-arm forever and never fire).
+  describe('max-wait ceiling', () => {
+    const T0 = 1_000_000; // arbitrary fixed epoch for deterministic tests
+
+    it('once a burst is armed, delay clamps to the remaining max-wait budget', () => {
+      // 1 minute into the burst the USER interval (60m) far exceeds the remaining
+      // max-wait budget (10m - 1m = 9m), so the delay is clamped DOWN to that
+      // remaining budget — the full interval is NOT used once a ceiling applies.
+      const { delay } = computeHistoryJob(page, 'user', T0, T0 + 60_000);
+      expect(delay).toBe(IDLE_MAX_WAIT_USER - 60_000);
+    });
+
+    it('never waits longer than the max-wait budget from the burst start', () => {
+      // A store arriving right at the ceiling → delay 0 (fire promptly).
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('past the ceiling never returns a negative delay', () => {
+      const { delay } = computeHistoryJob(
+        page,
+        'user',
+        T0,
+        T0 + IDLE_MAX_WAIT_USER + 5 * 60_000,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('the agent ceiling is shorter than the user ceiling', () => {
+      expect(IDLE_MAX_WAIT_AGENT).toBeLessThan(IDLE_MAX_WAIT_USER);
+      const { delay } = computeHistoryJob(
+        page,
+        'agent',
+        T0,
+        T0 + IDLE_MAX_WAIT_AGENT,
+      );
+      expect(delay).toBe(0);
+    });
+
+    it('without a burstStart there is no ceiling (backward-compatible)', () => {
+      expect(computeHistoryJob(page, 'user').delay).toBe(IDLE_INTERVAL_USER);
+      expect(computeHistoryJob(page, 'agent').delay).toBe(IDLE_INTERVAL_AGENT);
+    });
+  });
 });

 describe('resolveSource (truth table)', () => {
@@ -40,11 +40,12 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
  let pageHistoryRepo: {
    saveHistory: jest.Mock;
    findPageLastHistory: jest.Mock;
+    updateHistoryKind: jest.Mock;
  };
  let aiQueue: { add: jest.Mock };
-  let historyQueue: { add: jest.Mock };
+  let historyQueue: { add: jest.Mock; remove: jest.Mock };
  let notificationQueue: { add: jest.Mock };
-  let collabHistory: { addContributors: jest.Mock };
+  let collabHistory: { addContributors: jest.Mock; popContributors: jest.Mock };
  let transclusionService: {
    syncPageTransclusions: jest.Mock;
    syncPageReferences: jest.Mock;
@@ -93,13 +94,22 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
    pageHistoryRepo = {
      saveHistory: jest.fn().mockImplementation(async () => {
        callOrder.push('saveHistory');
+        return { id: 'history-1' };
      }),
      findPageLastHistory: jest.fn().mockResolvedValue(null),
+      updateHistoryKind: jest.fn().mockResolvedValue(undefined),
    };
    aiQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    historyQueue = { add: jest.fn().mockResolvedValue(undefined) };
+    historyQueue = {
+      add: jest.fn().mockResolvedValue(undefined),
+      // #370 — enqueuePageHistory now removes any pending idle job before re-adding.
+      remove: jest.fn().mockResolvedValue(undefined),
+    };
    notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
-    collabHistory = { addContributors: jest.fn().mockResolvedValue(undefined) };
+    collabHistory = {
+      addContributors: jest.fn().mockResolvedValue(undefined),
+      popContributors: jest.fn().mockResolvedValue([]),
+    };
    transclusionService = {
      syncPageTransclusions: jest.fn().mockResolvedValue(undefined),
      syncPageReferences: jest.fn().mockResolvedValue(undefined),
@@ -165,6 +175,50 @@ describe('PersistenceExtension.onStoreDocument — Approach-A boundary snapshot'
    expect(pageRepo.updatePage.mock.calls[0][0].lastUpdatedSource).toBe('user');
  });

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

+/**
+ * #370 — wire format of the client→server "save a version" signal. Sent by the
+ * human (Cmd+S / Save button) and by the agent's explicit save tool over the
+ * SAME stateless channel. The intentionality tier ('manual' vs 'agent') is
+ * derived SERVER-SIDE from the signed connection actor, never from this
+ * payload, so a version's type is unforgeable. The document is taken from the
+ * connection (not the payload), so the signal cannot be aimed at another page.
+ */
+export const SAVE_VERSION_MESSAGE_TYPE = 'save-version';
+
 /**
 * #251 — how long an intentional-clear signal stays "pending" before it is
 * ignored. The signal is set on the clearing keystroke but consumed by the
@@ -92,35 +104,39 @@ export function resolveSource(
 }

 /**
- * Compute the BullMQ job id + delay for a page-history snapshot job. Pure so
- * the data-loss-sensitive timing arithmetic is unit-testable; `now` is injected
- * (caller passes `Date.now()`) for determinism.
+ * #370 — compute the BullMQ job id + delay for a page's trailing idle-flush
+ * autosnapshot. Pure so the timing is unit-testable.
 *
- * - Agent edits: delay 0 and a source-keyed job id `${page.id}-agent`. The
- *   delay MUST stay 0 — the worker re-reads the page row at run time, so any
- *   delay risks reading content a later human edit has already overwritten
- *   (mis-tagged snapshot). 0 minimizes that window. The `-agent` suffix keeps
- *   the job from coalescing with the bare-page.id human job.
- * - Human edits: age-based debounce so rapid human edits coalesce into one
- *   snapshot; job id is the bare `page.id`.
- *
- * BullMQ forbids ':' in custom job ids (Redis key separator), so '-' is used;
- * page.id is a UUID, so `${page.id}-agent` cannot collide with a human job.
+ * Both humans and the agent now share ONE idle pipeline (the agent's old
+ * `delay=0` fast path is gone — intentional agent points arrive via the
+ * explicit save-version signal instead). The job id is the bare `page.id`, so a
+ * page has at most one pending idle job; the caller removes-and-re-adds it on
+ * every store to keep it debounced to the trailing edge of an edit burst. The
+ * window differs by source only: the agent flushes sooner than a human.
 */
 export function computeHistoryJob(
-  page: Pick<Page, 'id' | 'createdAt'>,
+  page: Pick<Page, 'id'>,
  source: string,
-  now: number,
+  // Epoch ms of the FIRST edit in the current burst (when the pending idle job
+  // was first armed). Used to enforce the max-wait ceiling so a continuous
+  // editing session cannot re-arm the trailing timer forever. `now` is injectable
+  // for tests; both default to a live clock / no ceiling when omitted.
+  burstStart?: number,
+  now: number = Date.now(),
 ): { jobId: string; delay: number } {
  const isAgent = source === 'agent';
-  const pageAge = now - new Date(page.createdAt).getTime();
-  const delay = isAgent
-    ? 0
-    : pageAge < HISTORY_FAST_THRESHOLD
-      ? HISTORY_FAST_INTERVAL
-      : HISTORY_INTERVAL;
-  const jobId = isAgent ? `${page.id}-agent` : page.id;
-  return { jobId, delay };
+  const interval = isAgent ? IDLE_INTERVAL_AGENT : IDLE_INTERVAL_USER;
+  const maxWait = isAgent ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+
+  let delay = interval;
+  if (burstStart !== undefined) {
+    // Time already elapsed since the burst's first edit; the snapshot must fire
+    // no later than `maxWait` after that, so shrink the trailing delay to the
+    // remaining budget (never negative, so BullMQ fires it promptly).
+    const remaining = burstStart + maxWait - now;
+    delay = Math.max(0, Math.min(interval, remaining));
+  }
+  return { jobId: page.id, delay };
 }

@Injectable()
@@ -132,6 +148,28 @@ export class PersistenceExtension implements Extension {
  // coalescing window" per document and OR it across all edits in the window,
  // so the snapshot is marked 'agent' regardless of who wrote last.
  private agentTouched: Map<string, boolean> = new Map();
+  // #370 — epoch ms of the FIRST edit in the current idle-flush burst. Keyed by
+  // documentName (like its sibling per-document maps above), NOT by page.id, so
+  // it can be cleaned in afterUnloadDocument alongside `contributors` /
+  // `agentTouched` / `intentionalClear` when the doc unloads — otherwise any page
+  // that was edited but never manually saved (the common case) would keep its
+  // entry forever and the Map would grow unbounded in this long-lived process.
+  // Set when the pending idle job is first armed (empty entry), read to enforce
+  // the max-wait ceiling in computeHistoryJob, and cleared on doc unload or when
+  // a manual save cancels the idle job so the next burst starts a fresh window.
+  //
+  // Single-process assumption (like `contributors` / `agentTouched` above): this
+  // lives only in THIS collab process's memory. A restart, or a page's ownership
+  // moving to another node, loses the burst-start marker. Consequence: a burst
+  // that spans the restart looks like a fresh burst to the surviving process, so
+  // its max-wait ceiling is re-anchored to the first post-restart edit — a single
+  // continuous session straddling a restart can therefore wait up to ~2× the cap
+  // for its idle snapshot (once for the lost pre-restart window, once for the new
+  // one). Bounded and benign (it only DELAYS a safety-net autosnapshot; manual
+  // saves are unaffected and the next quiet period always flushes), but the
+  // assumption and its consequence are recorded here so no one mistakes the
+  // in-memory marker for a durable, cross-process guarantee.
+  private idleBurstStart: Map<string, number> = new Map();
  // #251 — per-document "intentional clear pending" flags. Keyed by
  // documentName, value = expiry timestamp (ms). Set by onStateless when the
  // client reports a deliberate clear; consumed once by the next
@@ -363,20 +401,19 @@ export class PersistenceExtension implements Extension {
            //this.logger.debug('Contributors error:' + err?.['message']);
          }

-          // Approach A — boundary snapshot before the agent's first edit.
-          // When this store is the agent's and the page's currently persisted
-          // state was authored by a human, pin that human state as its own
-          // history version BEFORE the agent overwrites it. `page` still holds
-          // the OLD content/provenance here, so saveHistory(page) captures the
-          // pre-agent state tagged 'user'. The agent's new content is
-          // snapshotted later by the debounced PAGE_HISTORY job ('agent'). Skip
-          // if the prior state is already agent-authored (boundary already
-          // pinned on the user->agent transition), if the page is effectively
-          // empty, or if the latest existing snapshot already equals this human
-          // state (avoid duplicates).
+          // #370 — boundary snapshot on ANY source transition. When the store
+          // flips the page's provenance (user↔agent↔git), pin the OUTGOING
+          // state as its own history version BEFORE the incoming source
+          // overwrites it. `page` still holds the OLD content/provenance here,
+          // so saveHistory(page) captures the pre-transition state tagged with
+          // its own source, kind='boundary'. The incoming content is snapshotted
+          // later by the debounced idle job. Skip if the page is effectively
+          // empty or if the latest existing snapshot already equals this state
+          // (the shared isDeepStrictEqual gate — avoids duplicates). Generalizing
+          // beyond the old user→agent special-case also covers git-sync for free.
          if (
-            lastUpdatedSource === 'agent' &&
-            page.lastUpdatedSource !== 'agent'
+            page.lastUpdatedSource &&
+            page.lastUpdatedSource !== lastUpdatedSource
          ) {
            // pageHistory.pageId is uuid-typed; use page.id (never the doc-name
            // slugId) so a `page.<slugId>` doc cannot throw 22P02 here (#260).
@@ -384,15 +421,13 @@ export class PersistenceExtension implements Extension {
              page.id,
              { includeContent: true, trx },
            );
-            const humanBaselineMissing =
+            const baselineMissing =
              !lastHistory ||
              !isDeepStrictEqual(lastHistory.content, page.content);
-            if (
-              !isEmptyParagraphDoc(page.content as any) &&
-              humanBaselineMissing
-            ) {
+            if (!isEmptyParagraphDoc(page.content as any) && baselineMissing) {
              await this.pageHistoryRepo.saveHistory(page, {
                contributorIds: page.contributorIds ?? undefined,
+                kind: 'boundary',
                trx,
              });
            }
@@ -522,7 +557,7 @@ export class PersistenceExtension implements Extension {
        { jobId: `embed-${page.id}`, delay: EMBED_DEBOUNCE_MS },
      );

-      await this.enqueuePageHistory(page, lastUpdatedSource);
+      await this.enqueuePageHistory(page, documentName, lastUpdatedSource);
    }

    // #402 — report the serialized size for the store histogram's size_bucket.
@@ -554,6 +589,14 @@ export class PersistenceExtension implements Extension {
      return; // unrelated / malformed stateless message
    }

+    // #370 — explicit "save a version" (human Cmd+S / agent save tool). Edit
+    // rights are already enforced by the readOnly reject above (a reader can't
+    // create a version), exactly as intentional-clear requires.
+    if (message?.type === SAVE_VERSION_MESSAGE_TYPE) {
+      await this.handleSaveVersion(data);
+      return;
+    }
+
    if (message?.type !== INTENTIONAL_CLEAR_MESSAGE_TYPE) return;

    this.intentionalClear.set(
@@ -562,6 +605,160 @@ export class PersistenceExtension implements Extension {
    );
  }

+  /**
+   * #370 — persist an intentional version from the live in-memory ydoc.
+   *
+   * One stateless path serves BOTH the human and the agent; the tier is derived
+   * SERVER-SIDE from the signed connection actor ('agent' → 'agent', anything
+   * else → 'manual'), so the version type cannot be spoofed by the client. We
+   * take the fresh ydoc from the collab process memory and run it through the
+   * EXISTING store path first (so pages.content/ydoc reflect the exact content
+   * being versioned — a REST endpoint would race the up-to-10s-stale page row),
+   * then snapshot it into page_history with the intentional kind.
+   *
+   * Promote-not-dup: if the latest history row already holds this exact content
+   * and it is an autosave (idle/boundary/legacy-null), upgrade its kind in place
+   * instead of duplicating a heavy content row; if it is already 'manual', it is
+   * a no-op (the client shows an "already saved" toast). Otherwise a fresh
+   * version row is written, popping the aggregated contributors from Redis.
+   */
+  private async handleSaveVersion(data: onStatelessPayload): Promise<void> {
+    const { connection, document, documentName } = data;
+    const context = connection?.context;
+    const pageId = getPageId(documentName);
+    // Unforgeable: 'agent' only for a signed agent connection, else 'manual'.
+    const kind: PageHistoryKind =
+      context?.actor === 'agent' ? 'agent' : 'manual';
+
+    // Flush the live ydoc through the normal store path so the page row + ydoc
+    // hold exactly what we are about to version (also fires the idle enqueue we
+    // supersede below, plus any source-transition boundary). onStoreDocument
+    // only needs document/documentName/context.
+    await this.onStoreDocument({
+      document,
+      documentName,
+      context,
+    } as onStoreDocumentPayload);
+
+    let result:
+      | { historyId: string; kind: PageHistoryKind; alreadySaved: boolean }
+      | undefined;
+
+    // #370 F8-twin — the contributor set popped from Redis (destructive SPOP)
+    // must be restored if the version row does not durably land. The inner
+    // try/catch below only covers a throw INSIDE the callback; but executeTx
+    // COMMITS after the callback, so a commit-abort (serialization/deadlock/
+    // connection drop — the transient class the epic retries in the processor)
+    // rejects OUTSIDE the callback, after saveHistory already ran and the SPOP
+    // already happened, while the INSERT rolls back. onStateless does NOT retry,
+    // so an unrestored pop is a one-shot irrecoverable attribution loss (the
+    // processor got exactly this fix: poppedForRestore + an outer catch). We
+    // track the popped set here (keyed by the page UUID it was popped by — never
+    // the doc-name id, which may be a slugId, #260) and restore it in the outer
+    // catch. addContributors is an idempotent Redis SADD, so a double-restore is
+    // harmless. versionedPageId is also reused below to remove the superseded
+    // idle job by its real jobId (page.id).
+    let poppedForRestore: string[] = [];
+    let versionedPageId: string | undefined;
+
+    try {
+      await executeTx(this.db, async (trx) => {
+        const page = await this.pageRepo.findById(pageId, {
+          withLock: true,
+          includeContent: true,
+          trx,
+        });
+        if (!page) return;
+        versionedPageId = page.id;
+        // Never version an effectively-empty page (mirrors the processor's
+        // first-history guard); there is nothing intentional to pin.
+        if (isEmptyParagraphDoc(page.content as any)) return;
+
+        const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+          page.id,
+          { includeContent: true, trx },
+        );
+
+        if (
+          lastHistory &&
+          isDeepStrictEqual(lastHistory.content, page.content)
+        ) {
+          // Content is already snapshotted. Promote-not-dup.
+          if (lastHistory.kind === 'manual') {
+            result = {
+              historyId: lastHistory.id,
+              kind: 'manual',
+              alreadySaved: true,
+            };
+            return;
+          }
+          await this.pageHistoryRepo.updateHistoryKind(
+            lastHistory.id,
+            kind,
+            trx,
+          );
+          result = { historyId: lastHistory.id, kind, alreadySaved: false };
+          return;
+        }
+
+        // Fresh version row. Pop the contributors aggregated since the last
+        // snapshot (SPOP); restore them if the write fails so they aren't lost.
+        const contributorIds = await this.collabHistory.popContributors(
+          page.id,
+        );
+        poppedForRestore = contributorIds;
+        try {
+          const saved = await this.pageHistoryRepo.saveHistory(page, {
+            contributorIds,
+            kind,
+            trx,
+          });
+          result = { historyId: saved.id, kind, alreadySaved: false };
+        } catch (err) {
+          await this.collabHistory.addContributors(page.id, contributorIds);
+          poppedForRestore = [];
+          throw err;
+        }
+      });
+    } catch (err) {
+      // A throw here means the tx did NOT commit (callback threw, or the commit
+      // itself failed and rolled back). If we popped contributors and the inner
+      // catch did not already restore them, restore now so attribution is not
+      // lost — onStateless has no retry to recover it. Restore by the page UUID
+      // the pop was keyed under (versionedPageId is always set before the pop).
+      if (poppedForRestore.length && versionedPageId) {
+        await this.collabHistory.addContributors(
+          versionedPageId,
+          poppedForRestore,
+        );
+      }
+      throw err;
+    }
+
+    // Housekeeping: this explicit version supersedes the page's pending idle
+    // autosnapshot, so cancel it and end the current idle burst so the next edit
+    // starts a fresh max-wait window. Remove the idle job by its REAL jobId
+    // (page.id UUID — computeHistoryJob arms it under page.id), not the raw
+    // doc-name id which may be a slugId for a `page.<slugId>` doc (#260), or the
+    // remove silently misses. The burst marker is keyed by documentName (like its
+    // sibling per-document maps), and is also cleaned in afterUnloadDocument.
+    if (versionedPageId) {
+      await this.historyQueue.remove(versionedPageId).catch(() => undefined);
+    }
+    this.idleBurstStart.delete(documentName);
+
+    if (result) {
+      document.broadcastStateless(
+        JSON.stringify({
+          type: 'version.saved',
+          historyId: result.historyId,
+          kind: result.kind,
+          alreadySaved: result.alreadySaved,
+        }),
+      );
+    }
+  }
+
  async onChange(data: onChangePayload) {
    const documentName = data.documentName;
    const userId = data.context?.user?.id;
@@ -586,6 +783,10 @@ export class PersistenceExtension implements Extension {
    this.contributors.delete(documentName);
    this.agentTouched.delete(documentName);
    this.intentionalClear.delete(documentName);
+    // #370 — drop the idle-burst marker with the other per-document maps so it
+    // cannot accumulate across the process lifetime for never-manually-saved
+    // pages. The pending idle job (if any) is a self-expiring BullMQ delayed job.
+    this.idleBurstStart.delete(documentName);
  }

  private consumeContributors(documentName: string): string[] {
@@ -617,19 +818,80 @@ export class PersistenceExtension implements Extension {

  private async enqueuePageHistory(
    page: Page,
+    documentName: string,
    lastUpdatedSource: string,
  ): Promise<void> {
-    // Job id + delay arithmetic lives in the pure `computeHistoryJob` (see its
-    // doc comment for the agent-delay-0 / age-based-debounce invariants).
+    // #370 — trailing idle debounce with a max-wait ceiling. One pending idle
+    // job per page (jobId = page.id); on every store we remove the pending
+    // delayed job and re-add it, so the snapshot lands `delay` after edits go
+    // quiet rather than once per store (precedent: workspace.service.ts).
+    // remove() on a delayed job simply deletes it (0 if absent, no throw); if the
+    // job is already ACTIVE and the remove is a no-op, the add still de-dups and
+    // the processor's isDeepStrictEqual gate collapses the duplicate content.
+    //
+    // The FIRST arm of a burst records `burstStart`; computeHistoryJob shrinks
+    // the delay to the remaining max-wait budget from that point, so a continuous
+    // session cannot re-arm the trailing timer forever and starve the snapshot.
+    // A burst marker older than THIS TIER's max-wait means the previous idle job
+    // has already fired — start a fresh window instead of firing immediately on
+    // the next edit. Must use the SAME source-specific max-wait computeHistoryJob
+    // uses (agent 5m / user 10m): a hardcoded USER ceiling would leave an agent
+    // burst's marker stale for 5..10m, forcing delay=0 on every store in that
+    // window and writing one idle row per store — exactly the per-store bloat the
+    // debounce exists to prevent, on the continuous-agent path.
+    const maxWait =
+      lastUpdatedSource === 'agent' ? IDLE_MAX_WAIT_AGENT : IDLE_MAX_WAIT_USER;
+    const now = Date.now();
+    // Keyed by documentName (see the map declaration) so afterUnloadDocument can
+    // clean it; the queue jobId stays page.id (computeHistoryJob) as required.
+    let burstStart = this.idleBurstStart.get(documentName);
+    if (burstStart === undefined || now - burstStart >= maxWait) {
+      burstStart = now;
+      this.idleBurstStart.set(documentName, burstStart);
+    }
+
    const { jobId, delay } = computeHistoryJob(
      page,
      lastUpdatedSource,
-      Date.now(),
+      burstStart,
+      now,
    );

+    // remove-then-add trailing-debounce idiom, and its ONE race. We delete the
+    // pending delayed job and re-add it under the same jobId so the timer resets
+    // to the trailing edge of the burst. The race is the small window between
+    // these two awaits: if the delayed job's `delay` elapses in that gap it goes
+    // ACTIVE, and then:
+    //   - remove() on an active/locked job is a no-op (BullMQ won't yank a job a
+    //     worker holds), and our `.catch(() => undefined)` swallows that too; and
+    //   - add() with a jobId that already exists (the now-active job's id) is
+    //     DROPPED by BullMQ — a duplicate add is a no-op.
+    // So this store fails to re-arm the trailing job: the just-fired snapshot
+    // captured content up to the moment it went active, and THIS edit is left
+    // without a pending trailing job. It is bounded and self-healing — the NEXT
+    // store re-arms a fresh delayed job (the id is free again once the active job
+    // completes / removeOnComplete frees it), and the processor's
+    // isDeepStrictEqual gate collapses any content-identical duplicate. The only
+    // uncovered case is when the racing store was the LAST in the session: the
+    // tail edits made after the job went active get NO trailing snapshot until
+    // the next edit re-arms one. That is an acceptable safety-net gap (a manual
+    // Save, a source-transition boundary, or simply the next edit all still cover
+    // it), which is why the reviewer accepts documenting it here rather than
+    // adding a post-add "did the add actually arm a job?" re-check.
+    //
+    // NOTE — do NOT "unify" this with the neighbouring embed-debounce idiom
+    // (aiQueue.add of PAGE_CONTENT_UPDATED above): that one uses a STABLE jobId
+    // and NO remove(), relying purely on BullMQ coalescing a repeated add under
+    // the same id, because a re-embed only needs to eventually run once on the
+    // latest content and re-anchoring its delay on every keystroke is undesirable.
+    // THIS idiom deliberately removes-then-adds precisely to PUSH the delay back
+    // to the trailing edge on every store (a true debounce), which coalescing
+    // alone cannot do. Collapsing them would silently change the history cadence.
+    await this.historyQueue.remove(jobId).catch(() => undefined);
+
    await this.historyQueue.add(
      QueueJob.PAGE_HISTORY,
-      { pageId: page.id } as IPageHistoryJob,
+      { pageId: page.id, kind: 'idle' } as IPageHistoryJob,
      { jobId, delay },
    );
  }
@@ -66,6 +66,15 @@ describe('HistoryProcessor.process', () => {
    notificationQueue = { add: jest.fn().mockResolvedValue(undefined) };
    generalQueue = { add: jest.fn().mockResolvedValue(undefined) };

+    // #370 F3 — the processor now serializes its find+save under a page-row lock
+    // via executeTx. A db whose transaction().execute(fn) runs fn with a trx stub
+    // drives the real executeTx() helper without a database.
+    const db = {
+      transaction: () => ({
+        execute: (fn: (trx: any) => Promise<any>) => fn({ __trx: true }),
+      }),
+    };
+
    // WorkerHost's constructor reads `this.worker`; passing repos positionally
    // matches the constructor and avoids the Nest DI container.
    proc = new HistoryProcessor(
@@ -73,6 +82,7 @@ describe('HistoryProcessor.process', () => {
      pageRepo as any,
      collabHistory as any,
      watcherService as any,
+      db as any,
      notificationQueue as any,
      generalQueue as any,
    );
@@ -126,15 +136,26 @@ describe('HistoryProcessor.process', () => {
    await proc.process(buildJob());

    expect(collabHistory.popContributors).toHaveBeenCalledWith(PAGE_ID);
+    // #370 F3/F9 — the snapshot decision runs under a page-row lock. Pin the lock
+    // structurally so a refactor that drops withLock/trx (silently reintroducing
+    // the TOCTOU double-insert) turns this red. The tx stub is { __trx: true }.
+    expect(pageRepo.findById).toHaveBeenCalledWith(
+      PAGE_ID,
+      expect.objectContaining({ withLock: true, trx: { __trx: true } }),
+    );
+    // #370 F7 — addPageWatchers MUST receive the trx, or its FK-check runs on a
+    // separate connection and self-deadlocks against our FOR UPDATE. Asserting
+    // the trx arg here is exactly what would have caught that regression.
    expect(watcherService.addPageWatchers).toHaveBeenCalledWith(
      ['u1', 'u2'],
      PAGE_ID,
      SPACE_ID,
      WORKSPACE_ID,
+      { __trx: true },
    );
    expect(pageHistoryRepo.saveHistory).toHaveBeenCalledWith(
      expect.objectContaining({ id: PAGE_ID }),
-      { contributorIds: ['u1', 'u2'] },
+      { contributorIds: ['u1', 'u2'], kind: 'idle', trx: { __trx: true } },
    );
    expect(generalQueue.add).toHaveBeenCalledWith(
      QueueJob.PAGE_BACKLINKS,
@@ -186,6 +207,48 @@ describe('HistoryProcessor.process', () => {
    ]);
  });

+  it('COMMIT failure (throw outside the tx callback) → contributors RESTORED', async () => {
+    // #370 F8 — a commit-time failure throws OUTSIDE the callback, so the inner
+    // try/catch does not run; the outer catch must restore the popped set (else a
+    // BullMQ retry writes an unattributed version). Use a db whose execute() runs
+    // the callback THEN throws, simulating a commit abort.
+    pageHistoryRepo.findPageLastHistory.mockResolvedValue({
+      content: { type: 'doc', content: [] },
+    });
+    const commitFail = {
+      transaction: () => ({
+        execute: async (fn: (trx: any) => Promise<any>) => {
+          await fn({ __trx: true }); // callback succeeds (saveHistory ok)
+          throw new Error('commit aborted'); // ...but the COMMIT fails
+        },
+      }),
+    };
+    const procCommitFail = new HistoryProcessor(
+      pageHistoryRepo as any,
+      pageRepo as any,
+      collabHistory as any,
+      watcherService as any,
+      commitFail as any,
+      notificationQueue as any,
+      generalQueue as any,
+    );
+    jest
+      .spyOn(procCommitFail['logger'], 'error')
+      .mockImplementation(() => undefined);
+
+    await expect(procCommitFail.process(buildJob())).rejects.toThrow(
+      'commit aborted',
+    );
+    // The inner catch did NOT run (save succeeded), so only the outer catch can
+    // restore — assert it did.
+    expect(collabHistory.addContributors).toHaveBeenCalledWith(PAGE_ID, [
+      'u1',
+      'u2',
+    ]);
+    // And the post-snapshot queue work must NOT have run (we rethrew).
+    expect(generalQueue.add).not.toHaveBeenCalled();
+  });
+
  it('backlinks + notification queue failures are swallowed (history still committed)', async () => {
    pageHistoryRepo.findPageLastHistory.mockResolvedValue({
      content: { type: 'doc', content: [] },
@@ -19,6 +19,9 @@ import { isDeepStrictEqual } from 'node:util';
 import { CollabHistoryService } from '../services/collab-history.service';
 import { WatcherService } from '../../core/watcher/watcher.service';
 import { isEmptyParagraphDoc } from '../collaboration.util';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { executeTx } from '@docmost/db/utils';

@Processor(QueueName.HISTORY_QUEUE)
 export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
@@ -29,6 +32,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
    private readonly pageRepo: PageRepo,
    private readonly collabHistory: CollabHistoryService,
    private readonly watcherService: WatcherService,
+    @InjectKysely() private readonly db: KyselyDB,
    @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
    @InjectQueue(QueueName.GENERAL_QUEUE) private generalQueue: Queue,
  ) {
@@ -41,6 +45,9 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
    try {
      const { pageId } = job.data;

+      // Read the page WITHOUT a lock first, only to bail early on the two cheap
+      // no-write cases (page gone / empty first snapshot) without opening a
+      // transaction. The authoritative check-then-write happens locked below.
      const page = await this.pageRepo.findById(pageId, {
        includeContent: true,
      });
@@ -51,40 +58,109 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
        return;
      }

-      const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
-        pageId,
-        { includeContent: true },
-      );
+      // #370 F3 — the snapshot decision (findPageLastHistory → saveHistory) must
+      // be serialized against manual-save/boundary writers, which run under a
+      // page-row lock in onStoreDocument. Without it, this processor and a
+      // concurrent manual-save each read the same lastHistory (MVCC), both see
+      // content != lastHistory, and both insert — producing two page_history rows
+      // with IDENTICAL content (one 'idle', one 'manual'), defeating
+      // promote-not-dup and the version-vs-autosave split. Taking the same
+      // page-row lock makes the second writer observe the first's committed row so
+      // the isDeepStrictEqual gate collapses the duplicate. Only the read+write
+      // is transacted; the post-snapshot queue work stays outside.
+      let contributorIds: string[] = [];
+      let snapshotWritten = false;
+      let lastHistoryContent: unknown;
+      // #370 F8 — the contributor set popped from Redis (destructive SPOP) must be
+      // restored if the snapshot does not durably land. The inner try/catch only
+      // covers a throw INSIDE the callback; a COMMIT failure (connection drop,
+      // serialization/deadlock abort on commit — the transient class the epic
+      // already retries) throws OUTSIDE it, rolling the snapshot back while the
+      // pop is already gone. We track the popped set here and restore it in the
+      // outer catch so a BullMQ retry re-attributes the version. addContributors
+      // is an idempotent Redis SADD, so a double-restore is harmless.
+      let poppedForRestore: string[] = [];

-      if (!lastHistory && isEmptyParagraphDoc(page.content as any)) {
-        this.logger.debug(
-          `Skipping first history for page ${pageId}: empty content`,
-        );
-        await this.collabHistory.clearContributors(pageId);
+      try {
+        await executeTx(this.db, async (trx) => {
+          const lockedPage = await this.pageRepo.findById(pageId, {
+            includeContent: true,
+            withLock: true,
+            trx,
+          });
+          if (!lockedPage) return;
+
+          const lastHistory = await this.pageHistoryRepo.findPageLastHistory(
+            pageId,
+            { includeContent: true, trx },
+          );
+          lastHistoryContent = lastHistory?.content;
+
+          if (!lastHistory && isEmptyParagraphDoc(lockedPage.content as any)) {
+            this.logger.debug(
+              `Skipping first history for page ${pageId}: empty content`,
+            );
+            return;
+          }
+
+          if (
+            lastHistory &&
+            isDeepStrictEqual(lastHistory.content, lockedPage.content)
+          ) {
+            return; // already snapshotted at this content — nothing to write
+          }
+
+          contributorIds = await this.collabHistory.popContributors(pageId);
+          poppedForRestore = contributorIds;
+          try {
+            // Pass `trx` so the watcher insert's FK check (FOR KEY SHARE on
+            // pages[pageId]) runs on the SAME connection that already holds the
+            // FOR UPDATE lock from findById — otherwise it takes the FK lock on a
+            // separate pool connection and self-deadlocks against our own tx.
+            await this.watcherService.addPageWatchers(
+              contributorIds,
+              pageId,
+              lockedPage.spaceId,
+              lockedPage.workspaceId,
+              trx,
+            );
+
+            // #370 — every job on this queue is a trailing idle-flush autosnapshot.
+            await this.pageHistoryRepo.saveHistory(lockedPage, {
+              contributorIds,
+              kind: job.data.kind ?? 'idle',
+              trx,
+            });
+            snapshotWritten = true;
+            this.logger.debug(`History created for page: ${pageId}`);
+          } catch (err) {
+            await this.collabHistory.addContributors(pageId, contributorIds);
+            poppedForRestore = [];
+            throw err;
+          }
+        });
+      } catch (err) {
+        // A throw here means the tx did NOT commit (callback threw, or the commit
+        // itself failed and rolled back). If we popped contributors and the inner
+        // catch did not already restore them, restore now so the retry keeps
+        // attribution. snapshotWritten is irrelevant: it is set before commit, so
+        // it can be true even when the commit rolled the snapshot back.
+        if (poppedForRestore.length) {
+          await this.collabHistory.addContributors(pageId, poppedForRestore);
+        }
+        throw err;
+      }
+
+      // No snapshot written (page vanished / empty-first / unchanged content) →
+      // clear the contributor set for the skip cases and stop.
+      if (!snapshotWritten) {
+        if (!lastHistoryContent && isEmptyParagraphDoc(page.content as any)) {
+          await this.collabHistory.clearContributors(pageId);
+        }
        return;
      }

-      if (
-        !lastHistory ||
-        !isDeepStrictEqual(lastHistory.content, page.content)
-      ) {
-        const contributorIds = await this.collabHistory.popContributors(pageId);
-
-        try {
-          await this.watcherService.addPageWatchers(
-            contributorIds,
-            pageId,
-            page.spaceId,
-            page.workspaceId,
-          );
-
-          await this.pageHistoryRepo.saveHistory(page, { contributorIds });
-          this.logger.debug(`History created for page: ${pageId}`);
-        } catch (err) {
-          await this.collabHistory.addContributors(pageId, contributorIds);
-          throw err;
-        }
-
+      {
        const mentions = extractMentions(page.content);
        const pageMentions = extractPageMentions(mentions);
        const internalLinkSlugIds = extractInternalLinkSlugIds(page.content);
@@ -102,7 +178,7 @@ export class HistoryProcessor extends WorkerHost implements OnModuleDestroy {
            );
          });

-        if (contributorIds.length > 0 && lastHistory?.content) {
+        if (contributorIds.length > 0 && lastHistoryContent) {
          await this.notificationQueue
            .add(QueueJob.PAGE_UPDATED, {
              pageId,
@@ -0,0 +1,52 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import { readClientBuildVersion } from './client-version';
+
+describe('readClientBuildVersion', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(join(os.tmpdir(), 'client-version-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const writeVersionJson = (content: string) =>
+    fs.writeFileSync(join(dir, 'version.json'), content);
+
+  it('returns the version from a valid version.json', () => {
+    writeVersionJson(JSON.stringify({ version: 'test-A' }));
+    expect(readClientBuildVersion(dir)).toBe('test-A');
+  });
+
+  it('trims surrounding whitespace in the version', () => {
+    writeVersionJson(JSON.stringify({ version: '  v1.2.3  ' }));
+    expect(readClientBuildVersion(dir)).toBe('v1.2.3');
+  });
+
+  it('returns "" when version.json is missing', () => {
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" on malformed JSON', () => {
+    writeVersionJson('{ not json');
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is absent', () => {
+    writeVersionJson(JSON.stringify({ notVersion: 'x' }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is not a string', () => {
+    writeVersionJson(JSON.stringify({ version: 123 }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the path does not exist at all', () => {
+    expect(readClientBuildVersion(join(dir, 'nope'))).toBe('');
+  });
+});
@@ -0,0 +1,36 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+
+/**
+ * Resolve the absolute path to the built client bundle directory
+ * (`apps/client/dist`) shipped into the runtime image.
+ *
+ * The `../` depth is anchored on THIS module's compiled location
+ * (`dist/common/helpers`). `integrations/static` sits at the same depth under
+ * the compiled root, so both callers (StaticModule and readClientBuildVersion)
+ * MUST share this single helper rather than duplicating the depth — a copy in a
+ * module at a different depth would silently resolve to the wrong directory.
+ */
+export function resolveClientDistPath(): string {
+  return join(__dirname, '..', '..', '..', '..', 'client/dist');
+}
+
+/**
+ * Read the build version the client bundle was compiled with, from
+ * `<clientDistPath>/version.json` (written by the Vite build — the single
+ * source of truth shared by the baked-in `APP_VERSION` global and this file).
+ *
+ * Fail-safe: any error (missing file, unreadable, bad JSON, non-string
+ * version) yields `''`. The caller treats an empty version as "unknown" and
+ * the whole version-coherence feature stays silently inert — existing deploys
+ * without the file keep working unchanged.
+ */
+export function readClientBuildVersion(clientDistPath: string): string {
+  try {
+    const raw = fs.readFileSync(join(clientDistPath, 'version.json'), 'utf8');
+    const version = (JSON.parse(raw) as { version?: unknown }).version;
+    return typeof version === 'string' ? version.trim() : '';
+  } catch {
+    return '';
+  }
+}
@@ -3,3 +3,4 @@ export * from './nanoid.utils';
 export * from './file.helper';
 export * from './constants';
 export * from './security-headers';
+export * from './client-version';
@@ -189,10 +189,11 @@ export function stepBudgetWarning(stepNumber: number): string {
 //
 // `system` is the in-scope system prompt; we CONCATENATE so the original
 // persona/context is preserved — a bare `system` override would REPLACE the
-// whole system prompt for the step. `activatedTools` is PER-TURN mutable state
-// owned by the streaming loop (a closure Set grown by loadTools); it is passed
-// in (not module-global, not persisted) so this stays a pure function of its
-// arguments.
+// whole system prompt for the step. `activatedTools` is a closure Set grown by
+// loadTools and owned by the streaming loop; the caller seeds it from and
+// persists it to the chat's metadata across turns (#490), but this function only
+// READS the Set it is handed, so it stays a pure function of its arguments (not
+// module-global).
 //
 // NOTE: at AI SDK v7 the per-step `system` field is renamed to `instructions`.
 // On v6 (`^6.0.134`) `system` is the correct field — adjust when bumping.
@@ -1410,10 +1411,11 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
      const baseTools = { ...external.tools, ...docmostTools };

      // Deferred tool loading state (#332), scoped to THIS streaming loop:
-      //  - `activatedTools` is per-TURN mutable state — a fresh closure Set created
-      //    per streamText call, NOT module-global and NOT persisted, so a new turn
-      //    starts cold. loadTools.execute adds to it; prepareAgentStep reads it to
-      //    widen `activeTools` on the NEXT step.
+      //  - `activatedTools` is a fresh closure Set per streamText call (not
+      //    module-global), SEEDED from the chat's persisted metadata.activatedTools
+      //    (#490, just below) so activation carries across turns. loadTools.execute
+      //    adds to it; prepareAgentStep reads it to widen `activeTools` on the NEXT
+      //    step; turn end persists it back.
      //  - `validDeferredNames` = every tool that is NOT core (the in-app deferred
      //    tools + ALL external MCP tools), computed from the ACTUAL toolset so an
      //    external tool is loadable by its namespaced name. loadTools rejects any
@@ -0,0 +1,27 @@
+import { type Kysely } from 'kysely';
+
+/**
+ * #370 — page-versioning intentionality tier on a history snapshot.
+ *
+ * Adds `page_history.kind`, the three-tier "how intentional was this snapshot"
+ * marker that lets versions (intentional points) be told apart from autosaves:
+ *   - 'manual'   — a human explicitly saved a version (Cmd+S / Save button)
+ *   - 'agent'    — the AI agent explicitly saved a version
+ *   - 'idle'     — trailing idle-flush autosnapshot (safety net)
+ *   - 'boundary' — autosnapshot pinned on a source transition (user↔agent↔git)
+ *
+ * Nullable with NO default (mirrors last_updated_source in the agent-provenance
+ * migration): legacy rows predate the marker and read back as `null`, which the
+ * client renders as a plain autosave. Stored as a short varchar to stay
+ * forward-compatible without an enum migration.
+ */
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('page_history')
+    .addColumn('kind', 'varchar(20)', (col) => col)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.alterTable('page_history').dropColumn('kind').execute();
+}
@@ -13,6 +13,7 @@ import { jsonArrayFrom, jsonObjectFrom } from 'kysely/helpers/postgres';
 import { ExpressionBuilder, sql } from 'kysely';
 import { DB } from '@docmost/db/types/db';
 import { resolveAgentProvenance } from '../agent-provenance';
+import { PageHistoryKind } from '../../../collaboration/constants';

 /**
 * Role-resolution subquery for a page-history row's bound AI chat (#300). Joins
@@ -46,6 +47,9 @@ export class PageHistoryRepo {
    'lastUpdatedById',
    'lastUpdatedSource',
    'lastUpdatedAiChatId',
+    // #370 — intentionality tier ('manual' | 'agent' | 'idle' | 'boundary');
+    // null on legacy rows (= autosave). Selected so callers can read/promote it.
+    'kind',
    'contributorIds',
    'spaceId',
    'workspaceId',
@@ -85,9 +89,15 @@ export class PageHistoryRepo {

  async saveHistory(
    page: Page,
-    opts?: { contributorIds?: string[]; trx?: KyselyTransaction },
-  ): Promise<void> {
-    await this.insertPageHistory(
+    opts?: {
+      contributorIds?: string[];
+      // #370 — intentionality tier for this snapshot. Omitted → null (legacy
+      // autosave semantics). Callers derive it server-side, never from a client.
+      kind?: PageHistoryKind;
+      trx?: KyselyTransaction;
+    },
+  ): Promise<PageHistory> {
+    return await this.insertPageHistory(
      {
        pageId: page.id,
        slugId: page.slugId,
@@ -99,6 +109,7 @@ export class PageHistoryRepo {
        // Copy the provenance marker off the page row, as for lastUpdatedById.
        lastUpdatedSource: page.lastUpdatedSource,
        lastUpdatedAiChatId: page.lastUpdatedAiChatId,
+        kind: opts?.kind ?? null,
        contributorIds: opts?.contributorIds,
        spaceId: page.spaceId,
        workspaceId: page.workspaceId,
@@ -107,6 +118,25 @@ export class PageHistoryRepo {
    );
  }

+  /**
+   * #370 — promote an existing snapshot's intentionality tier in place. Used by
+   * the manual-save "promote-not-dup" path: when the latest history row already
+   * holds the exact content being versioned, we upgrade its `kind` instead of
+   * duplicating a heavy content row.
+   */
+  async updateHistoryKind(
+    pageHistoryId: string,
+    kind: PageHistoryKind,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    const db = dbOrTx(this.db, trx);
+    await db
+      .updateTable('pageHistory')
+      .set({ kind })
+      .where('id', '=', pageHistoryId)
+      .execute();
+  }
+
  async findPageHistoryByPageId(pageId: string, pagination: PaginationOptions) {
    const query = this.db
      .selectFrom('pageHistory')
@@ -280,6 +280,7 @@ export interface PageHistory {
  createdAt: Generated<Timestamp>;
  icon: string | null;
  id: Generated<string>;
+  kind: string | null;
  lastUpdatedAiChatId: string | null;
  lastUpdatedById: string | null;
  lastUpdatedSource: string | null;
@@ -0,0 +1,131 @@
+// p-limit and @sindresorhus/slugify are ESM-only and not in jest's transform
+// allowlist; both are irrelevant to createDrawioSvg (a pure fs + string method),
+// so they are mocked out to keep the module graph loadable under ts-jest.
+jest.mock('p-limit', () => ({
+  __esModule: true,
+  default: () => (fn: () => unknown) => fn(),
+}));
+jest.mock('@sindresorhus/slugify', () => ({
+  __esModule: true,
+  default: (input: string) => String(input),
+}));
+
+import { promises as fs } from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ImportAttachmentService } from './import-attachment.service';
+
+/**
+ * Unit test for ImportAttachmentService.createDrawioSvg (issue #507).
+ *
+ * The Confluence import wraps a `.drawio` file into a `.drawio.svg` attachment.
+ * The `content=` payload MUST be the mxfile XML entity-escaped (draw.io's native
+ * form), NOT base64 — draw.io's editor decodes a base64 content= via Latin-1
+ * atob, mangling every non-ASCII char into mojibake. createDrawioSvg touches no
+ * injected dependency, so the service is built with placeholder deps.
+ */
+describe('ImportAttachmentService.createDrawioSvg (#507)', () => {
+  const service = new ImportAttachmentService(
+    {} as any,
+    {} as any,
+    {} as any,
+  );
+  const call = (p: string): Promise<Buffer> =>
+    (service as any).createDrawioSvg(p);
+
+  let tmpDir: string;
+  beforeAll(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'drawio-507-'));
+  });
+  afterAll(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  const writeDrawio = async (name: string, xml: string): Promise<string> => {
+    const p = path.join(tmpDir, name);
+    await fs.writeFile(p, xml, 'utf-8');
+    return p;
+  };
+
+  it('writes content= as entity-encoded XML, not base64', async () => {
+    const drawio =
+      '<mxfile host="Confluence"><diagram name="Схема — ёж">' +
+      '<mxGraphModel><root><mxCell id="0"/>' +
+      '<mxCell id="2" value="Старт-бит" vertex="1" parent="0"/>' +
+      '</root></mxGraphModel></diagram></mxfile>';
+    const p = await writeDrawio('cyrillic.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+
+    // Entity-encoded XML form, starting with &lt;mxfile — never a base64 blob.
+    expect(content).toMatch(/^&lt;mxfile/);
+    expect(content).toContain('&lt;');
+    // Non-ASCII survives as raw UTF-8, with no Latin-1 mojibake.
+    expect(content).toContain('Старт-бит');
+    expect(content).toContain('Схема — ёж');
+    expect(content).not.toContain('Ð');
+
+    // Decoding the attribute (un-escaping) yields the original drawio file.
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+
+  it('encodes literal tab/newline/CR as numeric char-refs, not literal control chars (#507 F1)', async () => {
+    // A literal tab/newline/CR inside the mxfile XML would be collapsed to a
+    // single space by XML attribute-value normalization when the draw.io editor
+    // reads content=, silently flattening multi-line labels and tab-bearing
+    // values. They must be emitted as numeric char-refs instead.
+    const drawio =
+      '<mxfile><diagram name="p">' +
+      '<mxGraphModel><root><mxCell id="0"/>' +
+      '<mxCell id="2" value="col1\tcol2" style="html=1;\nshadow=0" vertex="1" parent="0"/>' +
+      '<mxCell id="3" value="Line1\nLine2\rLine3" vertex="1" parent="0"/>' +
+      '</root></mxGraphModel></diagram></mxfile>';
+    const p = await writeDrawio('ctrl.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+    // No literal control chars survive in the attribute value.
+    expect(content).not.toMatch(/[\t\n\r]/);
+    // They round-trip as numeric char-refs.
+    expect(content).toContain('&#x9;');
+    expect(content).toContain('&#xa;');
+    expect(content).toContain('&#xd;');
+    // Decoding (char-refs back to literal, entities back) recovers the file.
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&#x9;/gi, '\t')
+      .replace(/&#xa;/gi, '\n')
+      .replace(/&#xd;/gi, '\r')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+
+  it('escapes XML metacharacters in the drawio payload', async () => {
+    const drawio = '<mxfile><diagram name="a &amp; b">"q" &lt;x&gt;</diagram></mxfile>';
+    const p = await writeDrawio('meta.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+    // The attribute value must contain no bare `<`, `>` or `"` that would break
+    // out of the content="..." attribute or the SVG element.
+    expect(content).not.toMatch(/[<>"]/);
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+});
@@ -8,6 +8,7 @@ import { createReadStream } from 'node:fs';
 import { promises as fs } from 'fs';
 import { Readable } from 'stream';
 import { getMimeType, sanitizeFileName } from '../../../common/helpers';
+import { htmlEscape } from '../../../common/helpers/html-escaper';
 import { v7 } from 'uuid';
 import { FileTask } from '@docmost/db/types/entity.types';
 import { getAttachmentFolderPath } from '../../../core/attachment/attachment.utils';
@@ -849,7 +850,12 @@ export class ImportAttachmentService {
  ): Promise<Buffer> {
    try {
      const drawioContent = await fs.readFile(drawioPath, 'utf-8');
-      const drawioBase64 = Buffer.from(drawioContent).toString('base64');
+      // Write the mxfile XML XML-entity-escaped (draw.io's native content= form),
+      // NOT base64. draw.io's editor decodes a base64 content= via Latin-1 atob
+      // (no UTF-8 step), turning every non-ASCII char (Cyrillic, ё, —) into
+      // mojibake; the entity-encoded form is decoded by the DOM as UTF-8 and
+      // opens intact. Docmost's own decoder reads both forms.
+      const drawioEscaped = this.xmlEscapeContent(drawioContent);

      let imageElement = '';
      // If we have a PNG, include it in the SVG
@@ -875,7 +881,7 @@ export class ImportAttachmentService {
      width="600"
      height="400"
      viewBox="0 0 600 400"
-      content="${drawioBase64}">${imageElement}</svg>`;
+      content="${drawioEscaped}">${imageElement}</svg>`;

      return Buffer.from(svgContent, 'utf-8');
    } catch (error) {
@@ -884,6 +890,24 @@ export class ImportAttachmentService {
    }
  }

+  /**
+   * Escape a string so it is safe as the value of a double-quoted XML attribute
+   * (the `content=` payload of a `.drawio.svg`). The shared `htmlEscape` covers
+   * `& < > " '` (a strict superset of what this attribute needs; the extra `'`
+   * escape is harmless in a `"`-delimited value). On top of that, the numeric
+   * char-refs for tab/newline/CR are required: a literal tab/newline/CR inside
+   * an attribute value is collapsed to a single space by XML attribute-value
+   * normalization on DOM read (both our decoder and the real draw.io editor),
+   * silently flattening multi-line labels and tab-bearing values. Char-refs
+   * survive that normalization (#507).
+   */
+  private xmlEscapeContent(s: string): string {
+    return htmlEscape(s)
+      .replace(/\t/g, '&#x9;')
+      .replace(/\n/g, '&#xa;')
+      .replace(/\r/g, '&#xd;');
+  }
+
  private async uploadWithRetry(opts: {
    abs: string;
    storageFilePath: string;
@@ -20,6 +20,10 @@ export interface IStripeSeatsSyncJob {

 export interface IPageHistoryJob {
  pageId: string;
+  // #370 — intentionality tier the worker stamps on the snapshot. All jobs on
+  // this queue are trailing idle-flush autosnapshots, so this is 'idle' (absent
+  // → treated as 'idle' by the processor).
+  kind?: 'idle';
 }

 /**
@@ -4,6 +4,7 @@ import { join } from 'path';
 import * as fs from 'node:fs';
 import fastifyStatic from '@fastify/static';
 import { EnvironmentService } from '../environment/environment.service';
+import { resolveClientDistPath } from '../../common/helpers/client-version';

 /**
 * Resolve the response headers for a statically served client asset.
@@ -56,14 +57,7 @@ export class StaticModule implements OnModuleInit {
    const httpAdapter = this.httpAdapterHost.httpAdapter;
    const app = httpAdapter.getInstance();

-    const clientDistPath = join(
-      __dirname,
-      '..',
-      '..',
-      '..',
-      '..',
-      'client/dist',
-    );
+    const clientDistPath = resolveClientDistPath();

    const indexFilePath = join(clientDistPath, 'index.html');

@@ -9,10 +9,14 @@ import {
 import { Server, Socket } from 'socket.io';
 import { TokenService } from '../core/auth/services/token.service';
 import { JwtPayload, JwtType } from '../core/auth/dto/jwt-payload';
-import { OnModuleDestroy } from '@nestjs/common';
+import { Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
 import { WsService } from './ws.service';
 import { getSpaceRoomName, getUserRoomName } from './ws.utils';
+import {
+  readClientBuildVersion,
+  resolveClientDistPath,
+} from '../common/helpers/client-version';
 import * as cookie from 'cookie';

@WebSocketGateway({
@@ -20,17 +24,40 @@ import * as cookie from 'cookie';
  transports: ['websocket'],
 })
 export class WsGateway
-  implements OnGatewayConnection, OnGatewayInit, OnModuleDestroy
+  implements
+    OnGatewayConnection,
+    OnGatewayInit,
+    OnModuleInit,
+    OnModuleDestroy
 {
  @WebSocketServer()
  server: Server;

+  private readonly logger = new Logger(WsGateway.name);
+
+  // The build version of the client bundle shipped in this image, read once at
+  // startup from client/dist/version.json (single source of truth, same value
+  // baked into the client's APP_VERSION). Empty string => version.json missing
+  // or empty => the proactive version-coherence reload feature stays inert.
+  private appVersion = '';
+
  constructor(
    private tokenService: TokenService,
    private spaceMemberRepo: SpaceMemberRepo,
    private wsService: WsService,
  ) {}

+  onModuleInit(): void {
+    this.appVersion = readClientBuildVersion(resolveClientDistPath());
+    if (this.appVersion) {
+      this.logger.log(`app-version reload: ACTIVE (v=${this.appVersion})`);
+    } else {
+      this.logger.log(
+        'app-version reload: DISABLED (version.json missing/empty)',
+      );
+    }
+  }
+
  afterInit(server: Server): void {
    this.wsService.setServer(server);
  }
@@ -55,6 +82,14 @@ export class WsGateway
      const spaceRooms = userSpaceIds.map((id) => getSpaceRoomName(id));

      client.join([userRoom, workspaceRoom, ...spaceRooms]);
+
+      // Announce this container's client build version to the freshly
+      // authenticated socket. On a redeploy the client reconnects to the new
+      // container and receives the new version here, letting it guard-reload
+      // before it hits a stale lazy chunk. Per-connect only (no broadcast):
+      // natural reconnect covers both single-container and cluster without a
+      // thundering-herd fleet reload.
+      client.emit('app-version', { version: this.appVersion });
    } catch (err) {
      client.emit('Unauthorized');
      client.disconnect();
@@ -322,20 +322,21 @@ describe('AiChatService.stream [integration]', () => {
  });

  /**
-   * #332 deferred tool loading, the ON path. The riskiest property is that the
-   * per-turn `activatedTools` Set is created FRESH inside each stream() call, so a
-   * tool a previous turn activated via loadTools is NOT still active when the next
-   * turn starts — the new turn begins "cold" (CORE + loadTools only). The unit
-   * tests only exercise pure prepareAgentStep with hand-fed Sets; this pins the
-   * real wiring end-to-end (loadTools.execute -> activatedTools -> prepareStep ->
-   * per-step activeTools) against the real streamText loop, and proves there is no
-   * cross-turn leak. We drive a MockLanguageModelV3 whose step 1 calls
-   * loadTools(['createPage']) and assert, via the model's recorded per-step
-   * CallOptions.tools (the AI SDK filters the provider tool list by activeTools),
-   * that the deferred tool becomes active on the SAME turn's next step but NOT on a
-   * fresh turn's first step.
+   * #332 + #490 deferred tool loading, the ON path. Turn 1 starts COLD (CORE +
+   * loadTools only) and activates a deferred tool via loadTools; that activation
+   * is PERSISTED into the chat's metadata.activatedTools (#490) so the NEXT turn
+   * SEEDS from it and the tool is active from the fresh turn's FIRST step — the
+   * model never re-runs loadTools to re-activate the same tool. The unit tests
+   * only exercise pure prepareAgentStep with hand-fed Sets; this pins the real
+   * wiring end-to-end (loadTools.execute -> activatedTools -> persist -> next-turn
+   * seed -> prepareStep -> per-step activeTools) against the real streamText loop.
+   * We drive a MockLanguageModelV3 whose step 1 calls loadTools(['createPage'])
+   * and assert, via the model's recorded per-step CallOptions.tools (the AI SDK
+   * filters the provider tool list by activeTools), that the deferred tool becomes
+   * active on the SAME turn's next step AND, seeded from metadata, on the next
+   * turn's first step.
   */
-  describe('deferred tool loading ON — per-turn activation, no leak (#332)', () => {
+  describe('deferred tool loading ON — cross-turn activation persistence (#332 + #490)', () => {
    // A stub deferred (non-core) tool the agent can activate. Its execute is never
    // called — the model only needs to SEE it become active — but it must be a
    // valid AI-SDK tool so the SDK includes it in a step's tool list once active.
@@ -451,7 +452,7 @@ describe('AiChatService.stream [integration]', () => {
      } as any);
    }

-    it('activates a deferred tool for the SAME turn, and a NEW turn starts cold (no leak)', async () => {
+    it('activates a deferred tool for the SAME turn, and a NEW turn SEEDS it from persisted chat metadata (#490)', async () => {
      const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;

      // --- Turn 1: loadTools(createPage) on step 1, then answer on step 2. ---
@@ -474,7 +475,7 @@ describe('AiChatService.stream [integration]', () => {
      // Step 2 of the SAME turn sees the just-activated deferred tool.
      expect(step2Tools).toContain('createPage');

-      // --- Turn 2 on the SAME chat: must start cold again. ---
+      // --- Turn 2 on the SAME chat: seeds the persisted activation (#490). ---
      const model2 = new MockLanguageModelV3({
        doStream: async () => ({ stream: successStream() }),
      } as any);
@@ -485,9 +486,10 @@ describe('AiChatService.stream [integration]', () => {

      const nextTurnFirstStep = toolNames(model2.doStreamCalls[0]);
      expect(nextTurnFirstStep).toContain('loadTools');
-      // The activated set is per-turn: the prior turn's createPage did NOT leak,
-      // so the fresh turn's first step sees it deferred again.
-      expect(nextTurnFirstStep).not.toContain('createPage');
+      // #490: activation PERSISTS across turns — turn 1 wrote createPage into the
+      // chat's metadata.activatedTools, so the next turn seeds from it and the
+      // deferred tool is active from the FIRST step (no need to re-run loadTools).
+      expect(nextTurnFirstStep).toContain('createPage');
    });
  });
 });
@@ -0,0 +1,162 @@
+import { randomUUID } from 'node:crypto';
+import { Queue, Worker } from 'bullmq';
+import { PersistenceExtension } from '../../src/collaboration/extensions/persistence.extension';
+
+/**
+ * #370 — integration property of the idle-snapshot pipeline against REAL BullMQ.
+ *
+ * This is deliberately NOT a unit test of computeHistoryJob (that lives in
+ * compute-history-job.spec.ts). The point here is the OBSERVABLE end-to-end
+ * behaviour of the production `enqueuePageHistory` remove-then-add debounce
+ * driving a real Redis-backed delayed queue + worker (the #431→#439 class: a
+ * locally-correct function whose queue/timer property was never exercised):
+ *
+ *   - a CONTINUOUS burst of stores lasting several caps yields periodic idle
+ *     snapshots — at least one per max-wait cap, NOT one-per-store; and
+ *   - an INTERMITTENT burst (a few stores, then quiet) yields exactly ONE
+ *     trailing snapshot.
+ *
+ * We shrink the idle windows to milliseconds (jest.mock of collaboration
+ * constants) so real BullMQ delayed jobs actually promote within the test —
+ * fake timers cannot advance Redis's own delayed-set clock, so the intervals
+ * must be real but tiny. The production method under test is called verbatim.
+ */
+
+// NOTE: jest.mock is hoisted above the module's const initializers, so its
+// factory cannot close over MAX_WAIT_MS/INTERVAL_MS — the literals are inlined
+// here and MUST stay in sync with the consts below (a single source of truth is
+// impossible across the hoist boundary).
+jest.mock('../../src/collaboration/constants', () => {
+  const actual = jest.requireActual('../../src/collaboration/constants');
+  return {
+    ...actual,
+    IDLE_MAX_WAIT_USER: 300,
+    IDLE_MAX_WAIT_AGENT: 300,
+    IDLE_INTERVAL_USER: 1000,
+    IDLE_INTERVAL_AGENT: 1000,
+  };
+});
+
+// Mirrors the mocked IDLE_MAX_WAIT_* above (IDLE_INTERVAL_* is 1000 > this, so
+// the max-wait ceiling is what actually governs the trailing delay).
+const MAX_WAIT_MS = 300;
+
+const REDIS_CONNECTION = {
+  host: process.env.TEST_REDIS_HOST ?? '127.0.0.1',
+  port: Number(process.env.TEST_REDIS_PORT ?? 6379),
+};
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('#370 idle-snapshot pipeline (real BullMQ)', () => {
+  let queue: Queue;
+  let worker: Worker;
+  let extension: PersistenceExtension;
+  // Every processed snapshot, tagged by pageId so the two scenarios stay isolated.
+  const processed: Array<{ pageId: string; kind: string; at: number }> = [];
+  const queueName = `history-idle-int-${randomUUID()}`;
+
+  beforeAll(async () => {
+    queue = new Queue(queueName, {
+      connection: REDIS_CONNECTION,
+      // Mirror the production default (BullModule.forRoot removeOnComplete): the
+      // enqueue idiom relies on the jobId being freed once a job completes so the
+      // next burst can re-arm the same id.
+      defaultJobOptions: { removeOnComplete: true, removeOnFail: true },
+    });
+    await queue.waitUntilReady();
+
+    worker = new Worker(
+      queueName,
+      async (job) => {
+        processed.push({
+          pageId: job.data?.pageId,
+          kind: job.data?.kind,
+          at: Date.now(),
+        });
+      },
+      { connection: REDIS_CONNECTION },
+    );
+    await worker.waitUntilReady();
+
+    // Construct the real extension; only historyQueue (5th ctor arg) and the
+    // internal idleBurstStart map are exercised by enqueuePageHistory, so the
+    // other collaborators can be null — the constructor only assigns fields.
+    extension = new PersistenceExtension(
+      null as any, // pageRepo
+      null as any, // pageHistoryRepo
+      null as any, // db
+      null as any, // aiQueue
+      queue as any, // historyQueue
+      null as any, // notificationQueue
+      null as any, // collabHistory
+      null as any, // transclusionService
+    );
+  });
+
+  afterAll(async () => {
+    // Force-close and fully drain so no BullMQ background activity (delayed-set
+    // polling, blocking BRPOPLPUSH) bleeds into later suites in this single
+    // shared jest worker (maxWorkers: 1).
+    await worker?.close(true).catch(() => undefined);
+    await queue?.obliterate({ force: true }).catch(() => undefined);
+    await queue?.close();
+    // Let the redis sockets settle before the next suite starts.
+    await sleep(150);
+  });
+
+  const arm = (pageId: string) =>
+    (extension as any).enqueuePageHistory({ id: pageId }, 'user');
+
+  it('continuous burst over several caps → periodic idle snapshots (≥1 per cap, not one-per-store)', async () => {
+    const pageId = randomUUID();
+    const runMs = 6 * MAX_WAIT_MS; // ~6 caps of unbroken editing
+    // Store cadence that does NOT evenly divide the cap: real hocuspocus stores
+    // are not aligned to cap boundaries, so a boundary job promotes in the gap
+    // before the next store's remove(). A cap-aligned cadence would instead land
+    // a store exactly on every boundary and lose the snapshot to the documented
+    // remove-vs-active race — an artefact of the test clock, not the pipeline.
+    const stepMs = 70;
+    const stores = Math.floor(runMs / stepMs);
+
+    const start = Date.now();
+    let count = 0;
+    while (Date.now() - start < runMs) {
+      await arm(pageId);
+      count++;
+      await sleep(stepMs);
+    }
+    // Let the final armed job flush.
+    await sleep(2 * MAX_WAIT_MS);
+
+    const snaps = processed.filter((p) => p.pageId === pageId);
+
+    // Every autosnapshot is an idle-kind row.
+    expect(snaps.every((s) => s.kind === 'idle')).toBe(true);
+    // Periodic: at least one per cap over a multi-cap burst (lower-bounded loosely
+    // to stay robust; the property is "fires at least every cap", not a single
+    // trailing snapshot).
+    expect(snaps.length).toBeGreaterThanOrEqual(3);
+    // But NOT one-per-store: ~`stores` stores were issued; the debounce must
+    // collapse them to a small multiple of the cap count, nowhere near per-store.
+    expect(snaps.length).toBeLessThanOrEqual(Math.ceil(stores / 2));
+  });
+
+  it('intermittent burst (a few stores, then quiet) → exactly ONE trailing snapshot', async () => {
+    const pageId = randomUUID();
+
+    // A short burst well within a single cap window, then silence.
+    await arm(pageId);
+    await sleep(40);
+    await arm(pageId);
+    await sleep(40);
+    await arm(pageId);
+
+    // Wait comfortably past the cap so the single pending trailing job fires.
+    await sleep(4 * MAX_WAIT_MS);
+
+    const snaps = processed.filter((p) => p.pageId === pageId);
+    expect(snaps).toHaveLength(1);
+    expect(snaps[0].kind).toBe('idle');
+  });
+});
@@ -387,7 +387,7 @@ bucketByDay(sessions, tz):
 факты ниже — ground truth, можно дозапросить файлы через gitea MCP по указанному SHA):

 - `page_history.kind` — `varchar(20)`, NULLABLE, БЕЗ дефолта (migration
-  `20260705T120000-page-history-kind.ts`). Домен: `manual`/`agent`/`idle`/`boundary`;
+  `20260707T120000-page-history-kind.ts`). Домен: `manual`/`agent`/`idle`/`boundary`;
  legacy `null` = автосейв (`collaboration/constants.ts`, `PageHistoryKind`).
 - `kind` УЖЕ включён в `PageHistoryRepo.baseFields` (`page-history.repo.ts`) — читается всеми
  выборками истории. `saveHistory({kind})` и `updateHistoryKind(id, kind)` существуют.
@@ -178,10 +178,11 @@ function sliceModel(xml: string): string | null {
 // --- decode chain ----------------------------------------------------------

 /**
- * Read the `content=` attribute out of a `.drawio.svg` string. Docmost stores a
- * base64 payload there (createDrawioSvg); draw.io's own SVG export may store the
- * XML entity-encoded instead. The DOM decodes entities for us, so the caller
- * only has to distinguish "starts with '<'" (raw XML) from base64.
+ * Read the `content=` attribute out of a `.drawio.svg` string. Docmost writes
+ * the mxfile XML entity-encoded there (buildDrawioSvg / createDrawioSvg), which
+ * is also how draw.io's own SVG export stores it; older attachments stored a
+ * base64 payload instead. The DOM decodes entities for us, so the caller only
+ * has to distinguish "starts with '<'" (raw XML) from base64.
 */
 export function extractContentAttr(svg: string): string {
  const { doc, error } = parseXml(svg);
@@ -195,12 +196,23 @@ export function extractContentAttr(svg: string): string {
  // value itself never contains a double-quote (base64 / entity-encoded XML).
  const m = /content="([^"]*)"/.exec(svg);
  if (m) {
-    // Decode the handful of XML entities a raw regex would leave encoded.
+    // Decode the handful of XML entities a raw regex would leave encoded. The
+    // numeric char-refs for tab/newline/CR MUST be decoded here too: the DOM
+    // path above turns them back into the literal control chars, so this
+    // regex fallback has to agree or the two decode paths diverge (#507).
+    // `&amp;` is decoded last so an escaped `&amp;#x9;` reads back as the
+    // literal text `&#x9;`, not a tab.
    return m[1]
      .replace(/&lt;/g, "<")
      .replace(/&gt;/g, ">")
      .replace(/&quot;/g, '"')
      .replace(/&#39;/g, "'")
+      .replace(/&#x9;/gi, "\t")
+      .replace(/&#9;/g, "\t")
+      .replace(/&#xa;/gi, "\n")
+      .replace(/&#10;/g, "\n")
+      .replace(/&#xd;/gi, "\r")
+      .replace(/&#13;/g, "\r")
      .replace(/&amp;/g, "&");
  }
  throw new Error("drawio: SVG has no content= attribute to decode");
@@ -307,9 +319,16 @@ export function encodeDrawioFile(modelXml: string, title = "Page-1"): string {
 /**
 * Build the `diagram.drawio.svg` attachment. Mirrors the import service's
 * createDrawioSvg contract exactly:
- *   <svg xmlns=… xmlns:xlink=… content="${base64(drawioFile)}">${inner}</svg>
+ *   <svg xmlns=… xmlns:xlink=… content="${xmlEscape(drawioFile)}">${inner}</svg>
 * plus width/height/viewBox from the diagram bounding box and the schematic
 * preview as the visible children (`inner`).
+ *
+ * The `content=` value is the mxfile XML XML-entity-escaped (draw.io's own
+ * native form), NOT base64. draw.io's editor decodes a base64 content= via
+ * Latin-1 atob (no UTF-8 step), turning every non-ASCII char (e.g. Cyrillic,
+ * ё, —) into mojibake; the entity-encoded form is decoded by the DOM as UTF-8
+ * and opens intact. Our decoder (decodeDrawioSvg) reads both forms, so old
+ * base64 attachments still round-trip.
 */
 export function buildDrawioSvg(
  modelXml: string,
@@ -318,14 +337,14 @@ export function buildDrawioSvg(
  title = "Page-1",
 ): string {
  const file = encodeDrawioFile(modelXml, title);
-  const base64 = Buffer.from(file, "utf-8").toString("base64");
+  const content = xmlEscape(file);
  const w = Math.max(1, Math.round(bbox.width));
  const h = Math.max(1, Math.round(bbox.height));
  return (
    `<svg xmlns="http://www.w3.org/2000/svg" ` +
    `xmlns:xlink="http://www.w3.org/1999/xlink" ` +
    `width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" ` +
-    `content="${base64}">${inner}</svg>`
+    `content="${content}">${inner}</svg>`
  );
 }

@@ -334,7 +353,15 @@ function xmlEscape(s: string): string {
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
+    .replace(/"/g, "&quot;")
+    // A literal tab/newline/CR inside an attribute value is collapsed to a
+    // single space by XML attribute-value normalization on DOM read (both jsdom
+    // here and the real draw.io editor), silently flattening multi-line labels
+    // and tab-bearing values. Numeric char-refs survive that normalization, so
+    // emit them the way draw.io's own native export does (#507).
+    .replace(/\t/g, "&#x9;")
+    .replace(/\n/g, "&#xa;")
+    .replace(/\r/g, "&#xd;");
 }

 // --- normalization + hash --------------------------------------------------
@@ -51,6 +51,14 @@ const hasRule = (issues, rule, cellId) =>
    (i) => i.rule === rule && (cellId === undefined || i.cellId === cellId),
  );

+// Reverse the attribute-value XML escaping used in the `content=` payload.
+const unescapeAttr = (s) =>
+  s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&");
+
 // --- style parsing ---------------------------------------------------------

 test("parseStyle: base stylename + key=value pairs", () => {
@@ -335,16 +343,20 @@ test("encode/build: a title with < > \" & round-trips without corrupting the SVG

  // The outer content="..." attribute must not be broken by the title: the raw
  // title metacharacters never appear literally in the SVG markup (they are
-  // base64-encoded inside content=, and escaped inside the file XML).
+  // entity-escaped inside content=, doubly so where the file XML already escaped
+  // them inside name="...").
  const contentMatch = /content="([^"]*)"/.exec(svg);
  assert.ok(contentMatch, "SVG has a single well-formed content= attribute");

  // The diagram model still decodes losslessly despite the exotic title.
  assert.equal(decodeDrawioSvg(svg), model);

+  // content= is now entity-encoded XML (draw.io's native form), never base64.
+  assert.match(contentMatch[1], /^&lt;mxfile/);
+
  // The file XML is well-formed: the title lives in name="..." as escaped
  // entities, so unescaping recovers the original title byte-for-byte.
-  const fileXml = Buffer.from(contentMatch[1], "base64").toString("utf-8");
+  const fileXml = unescapeAttr(contentMatch[1]);
  const nameMatch = /<diagram id="[^"]*" name="([^"]*)">/.exec(fileXml);
  assert.ok(nameMatch, "the diagram name attribute is intact and quote-safe");
  const decodedTitle = nameMatch[1]
@@ -358,3 +370,112 @@ test("encode/build: a title with < > \" & round-trips without corrupting the SVG
  const file = encodeDrawioFile(model, title);
  assert.match(file, /name="A &lt; B &gt; C &quot; D &amp; E">/);
 });
+
+// --- #507: content= is entity-encoded XML, never base64 --------------------
+
+// A model whose cell values carry Cyrillic, ё and an em dash — exactly the
+// characters draw.io's Latin-1 atob mangles when content= is base64.
+const CYRILLIC_MODEL =
+  "<mxGraphModel><root>" +
+  '<mxCell id="0"/><mxCell id="1" parent="0"/>' +
+  '<mxCell id="2" value="Старт-бит — ёж" style="rounded=1;html=1;" vertex="1" parent="1">' +
+  '<mxGeometry x="100" y="100" width="120" height="60" as="geometry"/></mxCell>' +
+  "</root></mxGraphModel>";
+
+test("#507: buildDrawioSvg writes content= as entity-encoded XML (not base64)", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  const svg = buildDrawioSvg(model, "<g/>", { width: 200, height: 120 }, "Диаграмма");
+
+  const contentMatch = /content="([^"]*)"/.exec(svg);
+  assert.ok(contentMatch, "SVG has a single well-formed content= attribute");
+  const content = contentMatch[1];
+
+  // The content= value is the entity-encoded mxfile XML — starts with `&lt;mxfile`.
+  assert.match(content, /^&lt;mxfile/, "content= is entity-encoded mxfile XML");
+  // It must NOT be a base64 blob: base64 has no XML entities and no literal `<`.
+  assert.ok(content.includes("&lt;"), "content= carries XML entities, not base64");
+
+  // Cyrillic / ё / — survive verbatim in the attribute (raw UTF-8, not atob-mangled).
+  assert.ok(content.includes("Старт-бит — ёж"), "non-ASCII value is raw UTF-8 in content=");
+  assert.ok(content.includes("Диаграмма"), "non-ASCII title is raw UTF-8 in content=");
+  // The mojibake that base64+atob would have produced must be absent.
+  assert.ok(!content.includes("Ð"), "no Latin-1 mojibake in content=");
+});
+
+test("#507: Cyrillic model round-trips byte-stable through buildDrawioSvg -> decodeDrawioSvg", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  const svg = buildDrawioSvg(model, "<g/>", { width: 200, height: 120 }, "Заголовок — ё");
+  assert.equal(decodeDrawioSvg(svg), model);
+});
+
+test("#507 back-compat: an OLD base64-form .drawio.svg still decodes losslessly", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  // Reproduce the pre-fix write path: encodeDrawioFile -> base64 in content=.
+  const file = encodeDrawioFile(model, "Старая диаграмма");
+  const base64 = Buffer.from(file, "utf-8").toString("base64");
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" content="${base64}"><g/></svg>`;
+  // No XML entities, purely base64 alphabet — this is the legacy form.
+  assert.ok(!base64.includes("<") && !base64.includes("&"));
+  assert.equal(decodeDrawioSvg(svg), model);
+});
+
+test("#507 negative: non-ASCII in a cell value AND in the title round-trip clean", () => {
+  const model = normalizeXml(CYRILLIC_MODEL);
+  const title = "Тест — ёмкость № 5";
+  const svg = buildDrawioSvg(model, "<g/>", { width: 200, height: 120 }, title);
+
+  // Model recovered byte-for-byte.
+  assert.equal(decodeDrawioSvg(svg), model);
+
+  // Title lands in the <diagram name="..."> of the decoded file XML, intact.
+  const content = /content="([^"]*)"/.exec(svg)[1];
+  const fileXml = unescapeAttr(content);
+  const nameMatch = /<diagram id="[^"]*" name="([^"]*)">/.exec(fileXml);
+  assert.ok(nameMatch, "diagram name attribute present");
+  assert.equal(unescapeAttr(nameMatch[1]), title);
+});
+
+// --- #507 F1: literal tab/newline/CR in an attribute value survive the
+// content= round-trip. The whole mxfile XML lives in one content="..." attr;
+// XML attribute-value normalization collapses a LITERAL tab/newline/CR to a
+// single space on DOM read, so the escape must emit numeric char-refs instead.
+const CTRL_MODEL =
+  "<mxGraphModel><root>" +
+  '<mxCell id="0"/><mxCell id="1" parent="0"/>' +
+  '<mxCell id="2" value="col1\tcol2" style="html=1;\nshadow=0" vertex="1" parent="1">' +
+  '<mxGeometry x="10" y="10" width="120" height="60" as="geometry"/></mxCell>' +
+  '<mxCell id="3" value="Line1\nLine2\rLine3" vertex="1" parent="1">' +
+  '<mxGeometry x="10" y="100" width="120" height="60" as="geometry"/></mxCell>' +
+  "</root></mxGraphModel>";
+
+test("#507 F1: literal tab/newline/CR in a value round-trip byte-stable (DOM decode)", () => {
+  const svg = buildDrawioSvg(CTRL_MODEL, "<g/>", { width: 200, height: 200 });
+  const content = /content="([^"]*)"/.exec(svg)[1];
+  // The tab/newline/CR must be emitted as numeric char-refs, never as literal
+  // control chars (which DOM attribute-value normalization would eat).
+  assert.ok(
+    !/[\t\n\r]/.test(content),
+    "no literal tab/newline/CR survive in the content= attribute",
+  );
+  assert.ok(
+    content.includes("&#x9;") &&
+      content.includes("&#xa;") &&
+      content.includes("&#xd;"),
+    "tab/newline/CR are emitted as numeric char-refs",
+  );
+  // Full DOM decode recovers the model byte-for-byte, control chars intact.
+  assert.equal(decodeDrawioSvg(svg), CTRL_MODEL);
+});
+
+test("#507 F1: regex fallback decodes tab/newline/CR char-refs (agrees with DOM path)", () => {
+  const svg = buildDrawioSvg(CTRL_MODEL, "<g/>", { width: 200, height: 200 });
+  const content = /content="([^"]*)"/.exec(svg)[1];
+  // A bare `&` makes the SVG wrapper malformed, forcing extractContentAttr onto
+  // its regex fallback branch. That branch must decode the tab/newline/CR
+  // char-refs exactly like the DOM path, or the two decoders diverge.
+  const malformedSvg = `<svg content="${content}">&</svg>`;
+  assert.equal(decodeDrawioSvg(malformedSvg), CTRL_MODEL);
+  // The well-formed (DOM) path yields the identical result.
+  assert.equal(decodeDrawioSvg(svg), CTRL_MODEL);
+});