feat(work-time): redesign «Time worked» modal with time-of-day timelines (#566)

Port the NewDesign/TimeWorkedModal prototype onto the existing work-time
feature with zero backend changes. Each daily track now shows WHEN work
happened: a sticky 00/06/12/18/24 hour axis, shaded night hours (0–6, 21–24),
a per-block hover tooltip "start – end · duration", and a "now" boundary on
today's row. Work vs agent windows keep their existing colour semantics.

The prototype's invented props (DaySummary[], pre-made labels) are replaced by
a pure, unit-tested adapter (work-time-adapter.ts) over the real IPageWorkTime:
windows → time-of-day blocks (epoch kept for a DST-safe tooltip), ms → labels
via the shared formatters, in-place empty-run collapsing, and the today-only
now-line. The agent-only fail-safe (#395/#551) is preserved — the agent
estimate fills the main slot so it never renders empty.

Reuses usePageWorkTime, the endpoint, tz bucketing and format-work-time; deletes
the scratch prototype. New tooltip i18n key added to en-US/ru-RU.

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

.env.example

@@ -251,6 +251,16 @@ MCP_DOCMOST_PASSWORD=
 # Default 120000 (2 min).
 # AI_MCP_CALL_TIMEOUT_MS=120000
 
+# Kill-switch for the agent API-key feature (#501). Default ON when unset — a
+# deploy that never sets it must NOT silently kill every agent. STRICT parse:
+# only the literals `true` / `false` are accepted; a typo like `=0`/`=off`/`=False`
+# FAILS AT BOOT by design (never silently read as "enabled"), so the switch is
+# guaranteed to actually flip when an operator flips it during an incident. When
+# set to `false`: all api-key auth is DENIED (every api-key token is rejected) and
+# the api-key management endpoints return 404. The resolved state is logged at boot
+# (`API keys: ENABLED/DISABLED (API_KEYS_ENABLED=...)`) so it is verifiable per deploy.
+# API_KEYS_ENABLED=true
+
 # Max JSON/urlencoded request body size (bytes). Fastify's 1 MiB default is too
 # small for a long AI-chat research turn: the client resends the FULL message
 # history (every tool call + search result) on each turn, so a deep conversation's

.github/workflows/develop.yml

@@ -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
 

.github/workflows/test.yml

@@ -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
 

AGENTS.md

@@ -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
 

CHANGELOG.md

@@ -142,6 +142,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
@@ -392,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

Dockerfile

@@ -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/

NewDesign/CommentsPanel.tsx

@@ -0,0 +1,460 @@
+/**
+ * CommentsPanel — редизайн панели комментариев с фокусом на агентские правки.
+ * Mantine v7. Узкая колонка ~340–400px, светлая/тёмная темы.
+ *
+ * Реализованные решения (см. README.md):
+ *  - Дифф-первая карточка: цитата = старая строка диффа (без тройного дублирования)
+ *  - Группировка серии прогона под одной шапкой ("Корректор · 28 правок")
+ *  - Пакетное "Accept all" на фронте (по одной под капотом) с полоской прогресса
+ *  - Метки важности/категории парсятся клиентом из тегов "[Корректура][Существенно]"
+ *  - Фильтры по важности/категории
+ *  - Безопасный Dismiss через undo-тост (удаление откладывается на клиенте)
+ *  - Состояния: pending / applied / dismissed / conflict (потерян якорь)
+ *  - Крайние диффы: вставка (␣), удаление, одна буква, дефис→тире, длинный абзац
+ *  - Человеческий тред не деградирует (та же система, другое наполнение)
+ *  - Вкладки Open/Resolved сохранены
+ */
+import { useMemo, useState, useCallback, useRef } from 'react';
+import {
+  Box, Group, Stack, Text, Badge, Button, ActionIcon, Tabs, Progress,
+  Avatar, Tooltip, ScrollArea, useMantineColorScheme, useMantineTheme,
+} from '@mantine/core';
+import { notifications } from '@mantine/notifications';
+
+/* ─────────────────────────── Типы данных ─────────────────────────── */
+
+export type Severity = 'critical' | 'major' | 'minor';
+export type Category = string; // "Корректура" | "Факт" | "Стиль" | …
+
+/** Один сегмент интра-диффа: изменённый фрагмент подсвечивается. */
+export interface DiffSegment {
+  text: string;
+  changed: boolean;
+}
+
+/** Правка: сервер уже отдаёт посегментную разметку обеих строк. */
+export interface SuggestedEdit {
+  before: DiffSegment[]; // "было" (пустой массив ⇒ чистая вставка)
+  after: DiffSegment[];  // "стало" (пустой массив ⇒ чистое удаление)
+}
+
+export type CommentStatus = 'pending' | 'applied' | 'dismissed' | 'conflict';
+
+export interface Comment {
+  id: string;
+  runId?: string;          // id прогона агента — для группировки серии
+  authorName: string;      // "Корректор" | "Нарратор" | имя человека
+  authorKind: 'agent' | 'human';
+  triggeredBy?: string;    // кто запустил агента ("vvzvlad")
+  createdAtLabel: string;  // "15 ч", "2 дн" — форматируется вызывающим кодом
+  /** Сырой текст комментария от агента, метки в квадратных скобках. */
+  bodyRaw: string;
+  edit?: SuggestedEdit;    // есть ⇒ агентская правка; нет ⇒ обычный тред
+  status: CommentStatus;
+  replyCount?: number;
+  anchorLost?: boolean;    // сервер ответил конфликтом якоря
+}
+
+export interface CommentsPanelProps {
+  comments: Comment[];
+  /** Применить одну правку. Резолвит тред на сервере. */
+  onApply: (id: string) => Promise<void>;
+  /** Жёсткое удаление на сервере (для треда без ответов). Вызывается ПОСЛЕ окна undo. */
+  onDismiss: (id: string) => Promise<void>;
+  /** Резолв обычного треда. */
+  onResolve?: (id: string) => Promise<void>;
+  /** Клик по карточке/цитате — скролл документа к якорю и подсветка. */
+  onNavigateToAnchor: (id: string) => void;
+  onClose?: () => void;
+  /** Мс до фактического удаления после Dismiss (окно undo). По умолчанию 5000. */
+  dismissUndoMs?: number;
+}
+
+/* ───────────────────── Клиентский парсинг меток ───────────────────── */
+
+const SEVERITY_WORDS: Record<string, Severity> = {
+  'существенно': 'major', 'критично': 'critical', 'критическая': 'critical',
+  'незначительно': 'minor', 'мелко': 'minor', 'major': 'major',
+  'minor': 'minor', 'critical': 'critical',
+};
+
+interface ParsedBody {
+  category?: Category;
+  severity: Severity;
+  text: string; // тело без скобочных тегов
+}
+
+/** "[Корректура] [Существенно] Пробел…" → {category, severity, text}. */
+export function parseBody(raw: string): ParsedBody {
+  const tags: string[] = [];
+  const text = raw.replace(/\[([^\]]+)\]/g, (_, t) => { tags.push(t.trim()); return ''; }).trim();
+  let severity: Severity = 'minor';
+  let category: Category | undefined;
+  for (const t of tags) {
+    const sv = SEVERITY_WORDS[t.toLowerCase()];
+    if (sv) severity = sv; else if (!category) category = t;
+  }
+  return { category, severity, text };
+}
+
+const SEV_COLOR: Record<Severity, string> = {
+  critical: 'red', major: 'orange', minor: 'gray',
+};
+
+/* ──────────────────────────── Дифф ──────────────────────────── */
+
+/** Делает невидимые символы видимыми в подсветке (пробел, таб). */
+function visibleWhitespace(s: string): string {
+  return s.replace(/ /g, '␣').replace(/\t/g, '⇥');
+}
+
+function DiffLine({ segments, kind }: { segments: DiffSegment[]; kind: 'del' | 'ins' }) {
+  const theme = useMantineTheme();
+  const { colorScheme } = useMantineColorScheme();
+  const dark = colorScheme === 'dark';
+  const isDel = kind === 'del';
+  const sign = isDel ? '−' : '+';
+  const signColor = isDel ? theme.colors.red[dark ? 5 : 6] : theme.colors.green[dark ? 5 : 6];
+  const baseColor = isDel
+    ? (dark ? theme.colors.gray[5] : theme.colors.gray[6])
+    : (dark ? theme.colors.gray[1] : theme.colors.dark[9]);
+  const markBg = isDel
+    ? (dark ? 'rgba(224,49,49,.22)' : '#ffe3e3')
+    : (dark ? 'rgba(47,158,68,.22)' : '#d3f9d8');
+  const markFg = isDel
+    ? (dark ? theme.colors.red[3] : theme.colors.red[8])
+    : (dark ? theme.colors.green[3] : theme.colors.green[9]);
+
+  return (
+    <Group gap={7} wrap="nowrap" align="flex-start">
+      <Text ff="monospace" fw={600} fz={12} c={signColor} w={11} ta="center" style={{ flex: 'none', lineHeight: 1.5 }}>{sign}</Text>
+      <Text fz={13.5} c={baseColor} style={{ lineHeight: 1.45 }}>
+        {segments.map((seg, i) =>
+          seg.changed ? (
+            <Box key={i} component="mark" px={3} fw={600}
+              style={{ background: markBg, color: markFg, borderRadius: 3,
+                textDecoration: isDel ? 'line-through' : 'none' }}>
+              {visibleWhitespace(seg.text)}
+            </Box>
+          ) : (
+            <Box key={i} component="span" style={{ textDecoration: isDel ? 'line-through' : 'none' }}>{seg.text}</Box>
+          )
+        )}
+      </Text>
+    </Group>
+  );
+}
+
+function DiffBlock({ edit }: { edit: SuggestedEdit }) {
+  const pureInsert = edit.before.length === 0;
+  const pureDelete = edit.after.length === 0;
+  return (
+    <Stack gap={1}>
+      {!pureInsert && <DiffLine segments={edit.before} kind="del" />}
+      {!pureDelete && <DiffLine segments={edit.after} kind="ins" />}
+    </Stack>
+  );
+}
+
+/* ──────────────────────── Карточка правки ──────────────────────── */
+
+function EditCard({ c, onApply, onDismiss, onNavigateToAnchor, dismissUndoMs = 5000 }: {
+  c: Comment;
+  onApply: CommentsPanelProps['onApply'];
+  onDismiss: CommentsPanelProps['onDismiss'];
+  onNavigateToAnchor: CommentsPanelProps['onNavigateToAnchor'];
+  dismissUndoMs?: number;
+}) {
+  const parsed = useMemo(() => parseBody(c.bodyRaw), [c.bodyRaw]);
+  const [busy, setBusy] = useState(false);
+  const timer = useRef<number>();
+
+  const apply = useCallback(async () => {
+    setBusy(true);
+    try { await onApply(c.id); } finally { setBusy(false); }
+  }, [c.id, onApply]);
+
+  // Безопасный Dismiss: прячем сразу, удаляем на сервере после окна undo.
+  const dismiss = useCallback(() => {
+    let undone = false;
+    const nid = notifications.show({
+      message: 'Edit dismissed',
+      color: 'gray',
+      autoClose: dismissUndoMs,
+      withCloseButton: false,
+      // Кнопка "Вернуть" — см. README про кастомный рендер экшена.
+    });
+    timer.current = window.setTimeout(() => {
+      if (!undone) onDismiss(c.id);
+    }, dismissUndoMs);
+    // undo вызывается из UI: clearTimeout(timer.current); undone = true;
+    return { nid, cancel: () => { undone = true; clearTimeout(timer.current); } };
+  }, [c.id, onDismiss, dismissUndoMs]);
+
+  const conflict = c.status === 'conflict' || c.anchorLost;
+
+  return (
+    <Box
+      p="10px 12px"
+      onClick={() => onNavigateToAnchor(c.id)}
+      style={(t) => ({
+        cursor: 'pointer',
+        borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}`,
+      })}
+    >
+      <Stack gap={8}>
+        {c.edit && <DiffBlock edit={c.edit} />}
+
+        {conflict && (
+          <Group gap={7} wrap="nowrap" p="6px 8px"
+            style={(t) => ({ background: t.colorScheme === 'dark' ? 'rgba(230,180,20,.12)' : '#fff9db', borderRadius: 7 })}>
+            <Text fz={12}>⚠</Text>
+            <Text fz={12} c="yellow.8" style={{ lineHeight: 1.4 }}>Text changed — this edit can’t be applied</Text>
+          </Group>
+        )}
+
+        {parsed.text && !conflict && (
+          <Text fz={12.5} c="dimmed" style={{ lineHeight: 1.45 }}>{parsed.text}</Text>
+        )}
+
+        <Group gap={8} wrap="nowrap" onClick={(e) => e.stopPropagation()}>
+          <Box w={8} h={8} style={(t) => ({ flex: 'none', borderRadius: '50%', background: t.colors[SEV_COLOR[parsed.severity]][6] })} />
+          <Text fz={10} fw={600} tt="uppercase" c="dimmed" style={{ letterSpacing: '.06em', flex: 1, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>
+            {[parsed.category, parsed.severity === 'major' ? 'Major' : parsed.severity === 'critical' ? 'Critical' : null].filter(Boolean).join(' · ')}
+          </Text>
+
+          {c.status === 'applied' ? (
+            <Badge color="green" variant="light" radius="xl" size="sm">✓ Applied</Badge>
+          ) : c.status === 'dismissed' ? (
+            <Badge color="gray" variant="light" radius="xl" size="sm">Dismissed</Badge>
+          ) : conflict ? (
+            <Button size="compact-sm" variant="default" onClick={() => onNavigateToAnchor(c.id)}>Go to text</Button>
+          ) : (
+            <>
+              <Button size="compact-sm" variant="default" color="gray" onClick={dismiss}>Dismiss</Button>
+              <Button size="compact-sm" color="green" loading={busy} onClick={apply}>Apply</Button>
+            </>
+          )}
+        </Group>
+      </Stack>
+    </Box>
+  );
+}
+
+/* ──────────────────────── Человеческий тред ──────────────────────── */
+
+function HumanThread({ c, onResolve, onNavigateToAnchor }: {
+  c: Comment; onResolve?: CommentsPanelProps['onResolve']; onNavigateToAnchor: CommentsPanelProps['onNavigateToAnchor'];
+}) {
+  const parsed = useMemo(() => parseBody(c.bodyRaw), [c.bodyRaw]);
+  return (
+    <Box p="12px 14px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
+      <Stack gap={9}>
+        <Group gap={8} wrap="nowrap">
+          <Avatar size={26} radius="xl" color="orange">{c.authorName[0]}</Avatar>
+          <Text fz={12.5} fw={600}>{c.authorName}
+            <Text span c="dimmed" fw={400}> · {c.triggeredBy ? `${c.triggeredBy} · ` : ''}{c.createdAtLabel}</Text>
+          </Text>
+          <Box style={{ flex: 1 }} />
+          <Tooltip label="Resolve"><ActionIcon variant="default" size="md" onClick={() => onResolve?.(c.id)}>✓</ActionIcon></Tooltip>
+          <ActionIcon variant="default" size="md">⋯</ActionIcon>
+        </Group>
+        <Text fz={13.5} style={{ lineHeight: 1.5 }}>{parsed.text}</Text>
+        <Group gap={8}>
+          {c.replyCount ? <Text fz={12} c="dimmed">{c.replyCount} replies</Text> : null}
+          <Box style={{ flex: 1 }} />
+          <Button variant="subtle" size="compact-sm">Reply</Button>
+        </Group>
+      </Stack>
+    </Box>
+  );
+}
+
+/* ──────────────────── Шапка серии + прогресс ──────────────────── */
+
+function RunHeader({ runComments, onAcceptAll, progress }: {
+  runComments: Comment[];
+  onAcceptAll: () => void;
+  progress?: { done: number; total: number } | null;
+}) {
+  const head = runComments[0];
+  const majors = runComments.filter((c) => parseBody(c.bodyRaw).severity !== 'minor').length;
+  const applied = runComments.filter((c) => c.status === 'applied').length;
+  return (
+    <Box>
+      <Group gap={10} wrap="nowrap" p="11px 13px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
+        <Box style={{ position: 'relative', width: 30, height: 30, flex: 'none' }}>
+          <Avatar size={30} radius={8} color="teal">{head.authorName[0]}</Avatar>
+          {head.triggeredBy && (
+            <Avatar size={14} radius="xl" color="gray"
+              style={{ position: 'absolute', right: -4, bottom: -4, border: '2px solid var(--mantine-color-body)' }} />
+          )}
+        </Box>
+        <Stack gap={1} style={{ minWidth: 0 }}>
+          <Text fz={13} fw={600}>{head.authorName}
+            <Text span c="dimmed" fw={400}> · {head.triggeredBy} · {head.createdAtLabel}</Text>
+          </Text>
+          <Text fz={11.5} c="dimmed">
+            {runComments.length} edits · <Text span c="orange.7" fw={600}>{majors} major</Text> · {applied} applied
+          </Text>
+        </Stack>
+        <Box style={{ flex: 1 }} />
+        {!progress && <Button size="compact-sm" color="green" onClick={onAcceptAll}>Accept all</Button>}
+      </Group>
+      {progress && (
+        <Box p="9px 13px 11px" style={(t) => ({ background: t.colorScheme === 'dark' ? 'rgba(47,158,68,.08)' : '#f8fbf9', borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[2]}` })}>
+          <Group gap={8} mb={6}>
+            <Text fz={12} fw={600} c="green.7">Applying {progress.done} of {progress.total}…</Text>
+            <Box style={{ flex: 1 }} />
+            <Button variant="subtle" color="gray" size="compact-xs">Stop</Button>
+          </Group>
+          <Progress value={(progress.done / progress.total) * 100} color="green" size="sm" radius="xl" />
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/* ──────────────────────────── Панель ──────────────────────────── */
+
+/** Роль-автор для фильтра: у агентов — имя роли, у людей — «Пользователь». */
+function roleOf(c: Comment): string {
+  return c.authorKind === 'human' ? 'Пользователь' : c.authorName;
+}
+
+export function CommentsPanel(props: CommentsPanelProps) {
+  const { comments, onApply, onDismiss, onResolve, onNavigateToAnchor, onClose, dismissUndoMs } = props;
+  const [tab, setTab] = useState<'open' | 'resolved'>('open');
+  const [roleFilter, setRoleFilter] = useState<string | null>(null);
+  const [progress, setProgress] = useState<Record<string, { done: number; total: number }>>({});
+
+  const open = comments.filter((c) => c.status === 'pending' || c.status === 'conflict');
+  const resolved = comments.filter((c) => c.status === 'applied' || c.status === 'dismissed');
+  const list = tab === 'open' ? open : resolved;
+
+  const filtered = list.filter((c) => !roleFilter || roleOf(c) === roleFilter);
+
+  // Роли и счётчики для чипов-фильтров (только роли: Корректор / Фактчекер / Пользователь …).
+  const roles = useMemo(() => {
+    const order: string[] = [];
+    const count: Record<string, number> = {};
+    for (const c of list) {
+      const r = roleOf(c);
+      if (!(r in count)) { count[r] = 0; order.push(r); }
+      count[r]++;
+    }
+    return order.map((r) => ({ role: r, count: count[r] }));
+  }, [list]);
+
+  // Группировка агентских правок по runId; человеческие треды — по одному.
+  const groups = useMemo(() => {
+    const map = new Map<string, Comment[]>();
+    const singles: Comment[] = [];
+    for (const c of filtered) {
+      if (c.authorKind === 'agent' && c.runId && c.edit) {
+        if (!map.has(c.runId)) map.set(c.runId, []);
+        map.get(c.runId)!.push(c);
+      } else singles.push(c);
+    }
+    return { runs: [...map.entries()], singles };
+  }, [filtered]);
+
+  // Пакетное "Accept all" — по одной на фронте, обновляем прогресс.
+  const acceptAll = useCallback(async (runId: string, items: Comment[]) => {
+    const minor = items.filter((c) => parseBody(c.bodyRaw).severity === 'minor' && c.status === 'pending');
+    for (let i = 0; i < minor.length; i++) {
+      setProgress((p) => ({ ...p, [runId]: { done: i, total: minor.length } }));
+      try { await onApply(minor[i].id); } catch { /* конфликт — пропускаем, копим для сводки */ }
+    }
+    setProgress((p) => { const n = { ...p }; delete n[runId]; return n; });
+    notifications.show({ color: 'green', message: `${minor.length} applied` });
+  }, [onApply]);
+
+  return (
+    <Stack gap={0} h="100%" style={{ width: 380, maxWidth: '100%', borderLeft: '1px solid var(--mantine-color-default-border)' }}>
+      {/* Вкладки — статусная ось. Open/Resolved сохранены. */}
+      <Group gap={4} p="10px 14px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[2]}` })}>
+        <Tabs value={tab} onChange={(v) => setTab(v as 'open' | 'resolved')} variant="pills">
+          <Tabs.List>
+            <Tabs.Tab value="open" rightSection={<Badge size="sm" variant="light" color="blue">{open.length}</Badge>}>Open</Tabs.Tab>
+            <Tabs.Tab value="resolved" rightSection={<Badge size="sm" variant="light" color="gray">{resolved.length}</Badge>}>Resolved</Tabs.Tab>
+          </Tabs.List>
+        </Tabs>
+        <Box style={{ flex: 1 }} />
+        {onClose && <ActionIcon variant="subtle" color="gray" onClick={onClose}>✕</ActionIcon>}
+      </Group>
+
+      {/* Фильтры-чипы: только по ролям (Корректор / Фактчекер / Пользователь). */}
+      {tab === 'open' && roles.length > 1 && (
+        <ScrollArea type="never" p="8px 14px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
+          <Group gap={6} wrap="nowrap">
+            <FilterChip active={!roleFilter} onClick={() => setRoleFilter(null)} label={`All ${list.length}`} solid />
+            {roles.map(({ role, count }) => (
+              <FilterChip key={role} active={roleFilter === role} onClick={() => setRoleFilter(roleFilter === role ? null : role)} label={`${role} ${count}`} />
+            ))}
+          </Group>
+        </ScrollArea>
+      )}
+
+      {/* Лента */}
+      <ScrollArea style={{ flex: 1 }} bg="var(--mantine-color-default-hover)">
+        {filtered.length === 0 ? (
+          <EmptyState tab={tab} />
+        ) : (
+          <>
+            {groups.runs.map(([runId, items]) => (
+              <Box key={runId} m="6px 10px" bg="var(--mantine-color-body)" style={{ border: '1px solid var(--mantine-color-default-border)', borderRadius: 10, overflow: 'hidden' }}>
+                <RunHeader runComments={items} progress={progress[runId] ?? null} onAcceptAll={() => acceptAll(runId, items)} />
+                {items.map((c) => (
+                  <EditCard key={c.id} c={c} onApply={onApply} onDismiss={onDismiss} onNavigateToAnchor={onNavigateToAnchor} dismissUndoMs={dismissUndoMs} />
+                ))}
+              </Box>
+            ))}
+            {groups.singles.map((c) => (
+              <Box key={c.id} m="6px 10px" bg="var(--mantine-color-body)" style={{ border: '1px solid var(--mantine-color-default-border)', borderRadius: 10, overflow: 'hidden' }}>
+                {c.edit
+                  ? <EditCard c={c} onApply={onApply} onDismiss={onDismiss} onNavigateToAnchor={onNavigateToAnchor} dismissUndoMs={dismissUndoMs} />
+                  : <HumanThread c={c} onResolve={onResolve} onNavigateToAnchor={onNavigateToAnchor} />}
+              </Box>
+            ))}
+          </>
+        )}
+      </ScrollArea>
+    </Stack>
+  );
+}
+
+/* ─────────────────────── Мелкие компоненты ─────────────────────── */
+
+function FilterChip({ label, active, onClick, dot, solid }: {
+  label: string; active: boolean; onClick: () => void; dot?: string; solid?: boolean;
+}) {
+  return (
+    <Button
+      onClick={onClick}
+      size="compact-sm"
+      radius="xl"
+      variant={active ? 'filled' : 'default'}
+      color={active ? (solid ? 'dark' : 'blue') : 'gray'}
+      leftSection={dot ? <Box w={7} h={7} style={(t) => ({ borderRadius: '50%', background: t.colors[dot][6] })} /> : undefined}
+      styles={{ root: { flex: 'none' }, label: { fontWeight: 600, fontSize: 12 } }}
+    >
+      {label}
+    </Button>
+  );
+}
+
+function EmptyState({ tab }: { tab: 'open' | 'resolved' }) {
+  const isOpen = tab === 'open';
+  return (
+    <Stack align="center" gap={6} p="40px 20px">
+      <Avatar size={40} radius="xl" color={isOpen ? 'green' : 'gray'}>{isOpen ? '✓' : '◌'}</Avatar>
+      <Text fw={600} fz={13}>{isOpen ? 'All caught up' : 'Nothing here yet'}</Text>
+      <Text fz={12} c="dimmed" ta="center" style={{ lineHeight: 1.45 }}>
+        {isOpen ? 'No edits waiting on you.' : 'Applied and closed items will appear here.'}
+      </Text>
+    </Stack>
+  );
+}
+
+export default CommentsPanel;

NewDesign/PageHistoryModal.tsx

@@ -0,0 +1,362 @@
+/**
+ * PageHistoryModal — редизайн окна «Page history».
+ * Mantine v7. Light/dark. Полноразмерное модальное окно.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * ЧТО ЭТО
+ * ─────────────────────────────────────────────────────────────────────────
+ * Окно истории версий страницы. Слева — панель навигации: мини-календарь
+ * (heatmap: яркость дня = число ревизий, обводка = выбранный день) + плотный
+ * список ревизий (одна ревизия = одна строка). Справа — реально отрендеренная
+ * версия страницы с подсветкой изменений. Все контролы — в одну строку шапки.
+ *
+ * Ключевые решения:
+ *  - Плотный список: одна ревизия на строку (аватар · время · автор · [SAVED]).
+ *    Бейдж показывается ТОЛЬКО у сохранённых версий; всё остальное — autosave.
+ *  - Агентские ревизии визуально отличаются: квадратный глиф роли (К/Ф) вместо
+ *    круглого аватара пользователя + «via <кто запустил>».
+ *  - Календарь объединён со списком в одной панели (мини-календарь = date jumper).
+ *  - Highlight changes + навигация по изменениям (N of M, ↑/↓) вынесены в шапку.
+ *  - Текущая версия помечена; Restore для неё недоступен.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * УСТАНОВКА / ИСПОЛЬЗОВАНИЕ
+ * ─────────────────────────────────────────────────────────────────────────
+ *   import { PageHistoryModal, Revision } from './PageHistoryModal';
+ *
+ *   <PageHistoryModal
+ *     opened={open}
+ *     onClose={() => setOpen(false)}
+ *     revisions={revisions}                 // Revision[]
+ *     selectedId={selId}
+ *     onSelect={setSelId}                    // клик по ревизии → рендер справа
+ *     renderVersion={(rev) => <ArticleView versionId={rev.id} />}  // ваш рендер страницы
+ *     highlightChanges={hl}
+ *     onToggleHighlight={setHl}
+ *     changeNav={{ index: 1, total: 3, onPrev, onNext }}  // навигация по диффу
+ *     onlySaved={onlySaved}
+ *     onToggleOnlySaved={setOnlySaved}
+ *     onRestore={(rev) => api.restore(rev.id)}   // async; текущая версия → disabled
+ *   />
+ *
+ * Требует MantineProvider на корне приложения (defaultColorScheme="auto" для тем).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * ФОРМАТ ДАННЫХ
+ * ─────────────────────────────────────────────────────────────────────────
+ *   interface Revision {
+ *     id: string;
+ *     at: Date | string;        // время ревизии; форматируется вызывающим/util-ом
+ *     dayGroup: string;         // 'Today' | 'Yesterday' | 'Mon 12 Jul' — заголовок группы
+ *     saved: boolean;           // true → бейдж SAVED; false → autosave (без бейджа)
+ *     author: { name: string } & (
+ *       | { kind: 'human' }
+ *       | { kind: 'agent'; role: string; triggeredBy: string }  // роль + кто запустил
+ *     );
+ *     isCurrent?: boolean;      // текущая (последняя) версия — Restore недоступен
+ *   }
+ *
+ * Ревизии приходят плоским массивом; группировка по dayGroup — на клиенте.
+ * Никаких изменений API не требуется: агентское авторство берётся из author.kind.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * СОСТОЯНИЯ (нарисованы/поддержаны)
+ * ─────────────────────────────────────────────────────────────────────────
+ *  - Ревизия: обычная / hover / выбранная / текущая / агентская / человеческая.
+ *  - Restore: default / disabled (выбрана текущая) / loading (спиннер после клика).
+ *  - Highlight changes: on/off; при off навигация по изменениям неактивна.
+ *  - Пустая история: одна версия / нет ревизий → EmptyState.
+ *  - Тёмная тема: через токены Mantine (useMantineColorScheme, var(--mantine-*)).
+ */
+import { useMemo, useState, useCallback } from 'react';
+import {
+  Modal, Box, Group, Stack, Text, Switch, Avatar, Badge, Button, ActionIcon,
+  ScrollArea, useMantineTheme, useMantineColorScheme,
+} from '@mantine/core';
+
+/* ─────────────────────────── Типы ─────────────────────────── */
+
+export type Author =
+  | { name: string; kind: 'human' }
+  | { name: string; kind: 'agent'; role: string; triggeredBy: string };
+
+export interface Revision {
+  id: string;
+  at: Date | string;
+  atLabel: string;      // предформатированное «5:35AM»
+  dayGroup: string;     // «Today» | «Yesterday» | «Mon 12 Jul»
+  saved: boolean;
+  author: Author;
+  isCurrent?: boolean;
+}
+
+export interface CalendarDay {
+  label: string;        // «12»
+  inMonth: boolean;
+  count: number;        // число ревизий за день (для heatmap)
+  selected?: boolean;
+  date: Date | string;
+}
+
+export interface PageHistoryModalProps {
+  opened: boolean;
+  onClose: () => void;
+  revisions: Revision[];
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+  renderVersion: (rev: Revision | null) => React.ReactNode;
+  highlightChanges: boolean;
+  onToggleHighlight: (v: boolean) => void;
+  changeNav?: { index: number; total: number; onPrev: () => void; onNext: () => void };
+  onlySaved: boolean;
+  onToggleOnlySaved: (v: boolean) => void;
+  onRestore: (rev: Revision) => Promise<void>;
+  /** Ячейки текущего месяца календаря + управление. Необязательно — без него панель = только список. */
+  calendar?: {
+    monthLabel: string;      // «July 2025»
+    weekdays: string[];      // ['Mon',…,'Sun']
+    days: CalendarDay[];     // обычно 35/42 ячейки
+    onPrevMonth: () => void;
+    onNextMonth: () => void;
+    onToday: () => void;
+    onPickDay: (d: CalendarDay) => void;
+  };
+}
+
+/* ─────────────────────────── Утилиты представления ─────────────────────────── */
+
+const USER_PALETTE = ['#495057', '#e8590c', '#1c7ed6', '#7048e8', '#0ca678'];
+function userColor(name: string) {
+  let h = 0;
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0;
+  return USER_PALETTE[h % USER_PALETTE.length];
+}
+const AGENT_GRAD: Record<string, string> = {
+  'Корректор': 'linear-gradient(135deg,#20c997,#12b886)',
+  'Фактчекер': 'linear-gradient(135deg,#4c6ef5,#7048e8)',
+};
+function agentGrad(role: string) { return AGENT_GRAD[role] ?? 'linear-gradient(135deg,#868e96,#495057)'; }
+
+/** heatmap: число ревизий → фон/текст ячейки календаря. */
+function heat(n: number, dark: boolean) {
+  if (n === 0) return { bg: 'transparent', fg: dark ? '#5c5f66' : '#adb5bd' };
+  if (n <= 2) return { bg: dark ? 'rgba(34,139,230,.20)' : '#e7f0ff', fg: dark ? '#74c0fc' : '#1971c2' };
+  if (n <= 4) return { bg: dark ? 'rgba(34,139,230,.45)' : '#a5c8ff', fg: dark ? '#dbeafe' : '#0b3d91' };
+  return { bg: '#4c8dff', fg: '#ffffff' };
+}
+
+/* ─────────────────────────── Строка ревизии ─────────────────────────── */
+
+function RevisionRow({ rev, selected, onSelect }: { rev: Revision; selected: boolean; onSelect: () => void }) {
+  const theme = useMantineTheme();
+  const { colorScheme } = useMantineColorScheme();
+  const dark = colorScheme === 'dark';
+  const a = rev.author;
+  const isAgent = a.kind === 'agent';
+
+  return (
+    <Group
+      gap={8} wrap="nowrap" h={28} px="12px 14px" m="1px 6px"
+      onClick={onSelect}
+      style={{
+        cursor: 'pointer', borderRadius: 7,
+        background: selected ? (dark ? 'rgba(34,139,230,.14)' : '#eef4ff')
+          : isAgent ? (dark ? 'rgba(112,72,232,.06)' : '#fbfaff') : undefined,
+      }}
+    >
+      {/* аватар/глиф */}
+      {isAgent ? (
+        <Box style={{ flex: 'none', width: 16, height: 16, borderRadius: 4, background: agentGrad(a.role), display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#fff', font: '700 8px system-ui' }}>
+          {a.role[0]}
+        </Box>
+      ) : (
+        <Box style={{ flex: 'none', width: 16, height: 16, borderRadius: '50%', background: userColor(a.name), display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#fff', font: '700 8px system-ui' }}>
+          {a.name[0].toUpperCase()}
+        </Box>
+      )}
+      {/* время */}
+      <Text fz={12.5} fw={rev.isCurrent ? 600 : 500} c={rev.isCurrent ? undefined : 'dimmed'} style={{ flex: 'none', minWidth: 58 }}>
+        {rev.atLabel}
+      </Text>
+      {/* автор + via */}
+      <Group gap={4} wrap="nowrap" style={{ flex: 1, minWidth: 0, alignItems: 'baseline', overflow: 'hidden' }}>
+        <Text fz={12} fw={isAgent ? 600 : 400} c={isAgent ? undefined : 'dimmed'} truncate style={{ flex: 'none', maxWidth: 100 }}>
+          {isAgent ? a.role : a.name}
+        </Text>
+        {isAgent && <Text fz={11} c="dimmed" truncate>· via {a.triggeredBy}</Text>}
+      </Group>
+      {/* бейдж — только SAVED */}
+      {rev.saved && <Badge size="sm" radius="sm" variant="light" color="blue">SAVED</Badge>}
+    </Group>
+  );
+}
+
+/* ─────────────────────────── Мини-календарь ─────────────────────────── */
+
+function MiniCalendar({ cal }: { cal: NonNullable<PageHistoryModalProps['calendar']> }) {
+  const { colorScheme } = useMantineColorScheme();
+  const dark = colorScheme === 'dark';
+  return (
+    <Box p="10px 12px 8px" style={(t) => ({ borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
+      <Group gap={6} mb={6}>
+        <ActionIcon variant="subtle" color="gray" size="sm" onClick={cal.onPrevMonth}>‹</ActionIcon>
+        <Text fz={12} fw={600}>{cal.monthLabel}</Text>
+        <ActionIcon variant="subtle" color="gray" size="sm" onClick={cal.onNextMonth}>›</ActionIcon>
+        <Box style={{ flex: 1 }} />
+        <Button variant="subtle" size="compact-xs" onClick={cal.onToday}>Today</Button>
+      </Group>
+      <Box style={{ display: 'grid', gridTemplateColumns: 'repeat(7,1fr)', gap: 2, marginBottom: 2 }}>
+        {cal.weekdays.map((w) => (
+          <Text key={w} ta="center" fz={8.5} fw={600} c="dimmed">{w}</Text>
+        ))}
+      </Box>
+      <Box style={{ display: 'grid', gridTemplateColumns: 'repeat(7,1fr)', gap: 2 }}>
+        {cal.days.map((d, i) => {
+          const h = heat(d.count, dark);
+          return (
+            <Box
+              key={i} onClick={() => cal.onPickDay(d)}
+              style={{
+                position: 'relative', height: 26, borderRadius: 6, cursor: 'pointer',
+                display: 'flex', alignItems: 'center', justifyContent: 'center',
+                background: d.inMonth ? h.bg : 'transparent',
+                boxShadow: d.selected ? `inset 0 0 0 2px ${dark ? '#f1f3f5' : '#1a1b1e'}` : undefined,
+              }}
+            >
+              <Text fz={10.5} fw={d.selected ? 700 : 500} style={{ color: d.inMonth ? h.fg : (dark ? '#3a3d42' : '#dee2e6') }}>
+                {d.label}
+              </Text>
+            </Box>
+          );
+        })}
+      </Box>
+      {/* легенда heatmap */}
+      <Group gap={6} mt={8} align="center">
+        <Text fz={9.5} c="dimmed">fewer</Text>
+        {['#e7f0ff', '#a5c8ff', '#4c8dff'].map((c) => (
+          <Box key={c} style={{ width: 14, height: 10, borderRadius: 2, background: c }} />
+        ))}
+        <Text fz={9.5} c="dimmed">more revisions</Text>
+      </Group>
+    </Box>
+  );
+}
+
+/* ─────────────────────────── Окно ─────────────────────────── */
+
+export function PageHistoryModal(props: PageHistoryModalProps) {
+  const {
+    opened, onClose, revisions, selectedId, onSelect, renderVersion,
+    highlightChanges, onToggleHighlight, changeNav, onlySaved, onToggleOnlySaved,
+    onRestore, calendar,
+  } = props;
+  const [restoring, setRestoring] = useState(false);
+
+  const selected = revisions.find((r) => r.id === selectedId) ?? null;
+  const isEmpty = revisions.length <= 1;
+
+  // группировка по dayGroup, с фильтром Only saved
+  const groups = useMemo(() => {
+    const list = onlySaved ? revisions.filter((r) => r.saved) : revisions;
+    const map: { head: string; items: Revision[] }[] = [];
+    for (const r of list) {
+      let g = map.find((x) => x.head === r.dayGroup);
+      if (!g) { g = { head: r.dayGroup, items: [] }; map.push(g); }
+      g.items.push(r);
+    }
+    return map;
+  }, [revisions, onlySaved]);
+
+  const restore = useCallback(async () => {
+    if (!selected || selected.isCurrent) return;
+    setRestoring(true);
+    try { await onRestore(selected); } finally { setRestoring(false); }
+  }, [selected, onRestore]);
+
+  return (
+    <Modal
+      opened={opened} onClose={onClose} withCloseButton={false}
+      size="80rem" radius="lg" padding={0}
+      styles={{ body: { height: '80vh', maxHeight: 760, display: 'flex', flexDirection: 'column' } }}
+      overlayProps={{ backgroundOpacity: 0.5, blur: 1 }}
+    >
+      {/* ── single-row toolbar ── */}
+      <Group gap={14} h={60} px={16} wrap="nowrap" style={(t) => ({ flex: 'none', borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
+        <Text fz={16} fw={600}>Page history</Text>
+        <Box style={(t) => ({ width: 1, height: 22, background: t.colorScheme === 'dark' ? t.colors.dark[4] : t.colors.gray[2] })} />
+        <Stack gap={1} style={{ minWidth: 0 }}>
+          <Text fz={12} fw={600} truncate>{selected ? `${selected.dayGroup} · ${selected.atLabel}` : '—'}</Text>
+          <Text fz={10.5} c="dimmed">selected version</Text>
+        </Stack>
+
+        <Box style={{ flex: 1 }} />
+
+        {/* diff cluster */}
+        <Group gap={2} p={3} wrap="nowrap" style={(t) => ({ background: t.colorScheme === 'dark' ? t.colors.dark[6] : '#f4f6f8', borderRadius: 10 })}>
+          <Button variant="white" size="compact-sm" onClick={() => onToggleHighlight(!highlightChanges)}
+            leftSection={<Switch checked={highlightChanges} onChange={() => {}} size="xs" tabIndex={-1} styles={{ track: { cursor: 'pointer' } }} />}
+            styles={{ root: { boxShadow: '0 1px 2px rgba(0,0,0,.08)' } }}>
+            Highlight changes
+          </Button>
+          {changeNav && (
+            <>
+              <Text fz={12} fw={600} c="dimmed" px={6}>{changeNav.index} / {changeNav.total}</Text>
+              <Box style={{ display: 'flex' }}>
+                <ActionIcon variant="subtle" color="gray" size="lg" disabled={!highlightChanges} onClick={changeNav.onPrev} style={{ width: 26 }}>↑</ActionIcon>
+                <ActionIcon variant="subtle" color="gray" size="lg" disabled={!highlightChanges} onClick={changeNav.onNext} style={{ width: 26 }}>↓</ActionIcon>
+              </Box>
+            </>
+          )}
+        </Group>
+
+        <Box style={(t) => ({ width: 1, height: 22, background: t.colorScheme === 'dark' ? t.colors.dark[4] : t.colors.gray[2] })} />
+
+        <Button color="blue" onClick={restore} loading={restoring} disabled={!selected || selected.isCurrent}>
+          Restore this version
+        </Button>
+        <ActionIcon variant="subtle" color="gray" size="lg" onClick={onClose}>✕</ActionIcon>
+      </Group>
+
+      {/* ── body ── */}
+      <Box style={{ flex: 1, display: 'flex', minHeight: 0 }}>
+        {/* left: nav panel */}
+        <Stack gap={0} style={(t) => ({ flex: 'none', width: 280, minHeight: 0, borderRight: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}`, background: t.colorScheme === 'dark' ? t.colors.dark[7] : '#fcfcfd' })}>
+          <Group h={44} px={16} style={(t) => ({ flex: 'none', borderBottom: `1px solid ${t.colorScheme === 'dark' ? t.colors.dark[5] : t.colors.gray[1]}` })}>
+            <Switch checked={onlySaved} onChange={(e) => onToggleOnlySaved(e.currentTarget.checked)} size="sm" label="Only saved" labelPosition="right" styles={{ label: { fontSize: 13, fontWeight: 500 } }} />
+          </Group>
+
+          {calendar && <MiniCalendar cal={calendar} />}
+
+          <ScrollArea style={{ flex: 1 }}>
+            {groups.map((g) => (
+              <Box key={g.head}>
+                <Text px={16} pt={9} pb={5} fz={10.5} fw={600} tt="uppercase" c="dimmed" style={{ letterSpacing: '.05em', position: 'sticky', top: 0, zIndex: 2, background: 'var(--mantine-color-body)' }}>
+                  {g.head}
+                </Text>
+                {g.items.map((r) => (
+                  <RevisionRow key={r.id} rev={r} selected={r.id === selectedId} onSelect={() => onSelect(r.id)} />
+                ))}
+              </Box>
+            ))}
+          </ScrollArea>
+        </Stack>
+
+        {/* right: rendered version */}
+        <ScrollArea style={{ flex: 1, minWidth: 0 }} bg="var(--mantine-color-default-hover)">
+          {isEmpty ? (
+            <Stack align="center" justify="center" h="100%" gap={6} p={40}>
+              <Text fw={600} fz={14}>No earlier versions</Text>
+              <Text fz={12.5} c="dimmed" ta="center">У страницы пока одна версия — сравнивать не с чем.</Text>
+            </Stack>
+          ) : (
+            <Box p="26px 0" maw={660} mx="auto">
+              {renderVersion(selected)}
+            </Box>
+          )}
+        </ScrollArea>
+      </Box>
+    </Modal>
+  );
+}
+
+export default PageHistoryModal;

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

@@ -1,4 +1,8 @@
 {
+  "1 year": "1 year",
+  "30 days": "30 days",
+  "90 days": "90 days",
+  "A new version is available": "A new version is available",
   "Account": "Account",
   "Active": "Active",
   "Add": "Add",
@@ -9,11 +13,16 @@
   "Add space members": "Add space members",
   "Add to favorites": "Add to favorites",
   "Admin": "Admin",
+  "API key created": "API key created",
+  "API key revoked": "API key revoked",
+  "API keys across the workspace.": "API keys across the workspace.",
   "Are you sure you want to delete this group? Members will lose access to resources this group has access to.": "Are you sure you want to delete this group? Members will lose access to resources this group has access to.",
   "Are you sure you want to delete this page?": "Are you sure you want to delete this page?",
   "Are you sure you want to remove this user from the group? The user will lose access to resources this group has access to.": "Are you sure you want to remove this user from the group? The user will lose access to resources this group has access to.",
   "Are you sure you want to remove this user from the space? The user will lose all access to this space.": "Are you sure you want to remove this user from the space? The user will lose all access to this space.",
   "Are you sure you want to restore this version? Any changes not versioned will be lost.": "Are you sure you want to restore this version? Any changes not versioned will be lost.",
+  "Are you sure you want to revoke \"{{name}}\"? Any client using this key will immediately lose access. This cannot be undone.": "Are you sure you want to revoke \"{{name}}\"? Any client using this key will immediately lose access. This cannot be undone.",
+  "Author": "Author",
   "Can become members of groups and spaces in workspace": "Can become members of groups and spaces in workspace",
   "Can create and edit pages in space.": "Can create and edit pages in space.",
   "Can edit": "Can edit",
@@ -32,7 +41,9 @@
   "Confirm": "Confirm",
   "Copy as Markdown": "Copy as Markdown",
   "Copy link": "Copy link",
+  "Copy your API key now and store it somewhere safe. For security reasons it will not be shown again.": "Copy your API key now and store it somewhere safe. For security reasons it will not be shown again.",
   "Create": "Create",
+  "Create API key": "Create API key",
   "Create group": "Create group",
   "Create page": "Create page",
   "Create space": "Create space",
@@ -54,7 +65,14 @@
   "e.g Sales": "e.g Sales",
   "e.g Space for product team": "e.g Space for product team",
   "e.g Space for sales team to collaborate": "e.g Space for sales team to collaborate",
+  "e.g. CI deploy token": "e.g. CI deploy token",
   "Edit": "Edit",
+  "Expiring soon": "Expiring soon",
+  "Failed to create API key": "Failed to create API key",
+  "Failed to load API keys.": "Failed to load API keys.",
+  "Failed to revoke API key": "Failed to revoke API key",
+  "Never used": "Never used",
+  "No API keys yet": "No API keys yet",
   "Read": "Read",
   "Edit group": "Edit group",
   "Email": "Email",
@@ -133,6 +151,8 @@
   "page": "page",
   "Page deleted successfully": "Page deleted successfully",
   "Page history": "Page history",
+  "Revoke API key": "Revoke API key",
+  "Revoke {{name}}": "Revoke {{name}}",
   "Select version": "Select version",
   "Highlight changes": "Highlight changes",
   "Page import is in progress. Please do not close this tab.": "Page import is in progress. Please do not close this tab.",
@@ -188,6 +208,9 @@
   "Template": "Template",
   "Templates": "Templates",
   "Theme": "Theme",
+  "This key expires within 30 days": "This key expires within 30 days",
+  "This key has expired": "This key has expired",
+  "This key never expires": "This key never expires",
   "To change your email, you have to enter your password and new email.": "To change your email, you have to enter your password and new email.",
   "Toggle full page width": "Toggle full page width",
   "Unable to import pages. Please try again.": "Unable to import pages. Please try again.",
@@ -195,6 +218,7 @@
   "Untitled": "Untitled",
   "Updated successfully": "Updated successfully",
   "User": "User",
+  "Within the last hour": "Within the last hour",
   "Workspace": "Workspace",
   "Workspace Name": "Workspace Name",
   "Workspace settings": "Workspace settings",
@@ -239,6 +263,8 @@
   "Comment re-opened successfully": "Comment re-opened successfully",
   "Comment unresolved successfully": "Comment unresolved successfully",
   "Failed to resolve comment": "Failed to resolve comment",
+  "Failed to re-open comment": "Failed to re-open comment",
+  "Comment no longer exists": "Comment no longer exists",
   "Resolve comment": "Resolve comment",
   "Unresolve comment": "Unresolve comment",
   "Resolve Comment Thread": "Resolve Comment Thread",
@@ -423,6 +449,7 @@
   "Write anything. Enter \"/\" for commands": "Write anything. Enter \"/\" for commands",
   "Write...": "Write...",
   "Column count": "Column count",
+  "Your personal API keys.": "Your personal API keys.",
   "{{count}} Columns": "{{count}} Columns",
   "{{count}} command available_one": "1 command available",
   "{{count}} command available_other": "{{count}} commands available",
@@ -1427,5 +1454,21 @@
   "Boundary": "Boundary",
   "Autosave": "Autosave",
   "Only versions": "Only versions",
-  "No saved versions yet.": "No saved versions yet."
+  "No saved versions yet.": "No saved versions yet.",
+  "Time worked on this article": "Time worked on this article",
+  "Show time worked on this page": "Show time worked on this page",
+  "Estimated time worked (inactivity gap {{gap}} min)": "Estimated time worked (inactivity gap {{gap}} min)",
+  "Estimate · timezone {{tz}} · inactivity gap {{gap}} min": "Estimate · timezone {{tz}} · inactivity gap {{gap}} min",
+  "No editing activity recorded yet.": "No editing activity recorded yet.",
+  "× {{count}} days without edits": "× {{count}} days without edits",
+  "agent: {{value}}": "agent: {{value}}",
+  "Work": "Work",
+  "Agent": "Agent",
+  "{{start}} – {{end}} · {{duration}}": "{{start}} – {{end}} · {{duration}}",
+  "≈ {{hours}}h {{minutes}}m": "≈ {{hours}}h {{minutes}}m",
+  "≈ {{hours}}h": "≈ {{hours}}h",
+  "≈ {{minutes}}m": "≈ {{minutes}}m",
+  "{{hours}}h {{minutes}}m": "{{hours}}h {{minutes}}m",
+  "{{hours}}h": "{{hours}}h",
+  "{{minutes}}m": "{{minutes}}m"
 }

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

@@ -1,4 +1,8 @@
 {
+  "1 year": "1 год",
+  "30 days": "30 дней",
+  "90 days": "90 дней",
+  "A new version is available": "Доступна новая версия",
   "Account": "Аккаунт",
   "Active": "Активный",
   "Add": "Добавить",
@@ -9,11 +13,16 @@
   "Add space members": "Добавить участников пространства",
   "Add to favorites": "Добавить в избранное",
   "Admin": "Администратор",
+  "API key created": "API ключ создан",
+  "API key revoked": "API ключ отозван",
+  "API keys across the workspace.": "API ключи всего рабочего пространства.",
   "Are you sure you want to delete this group? Members will lose access to resources this group has access to.": "Вы уверены, что хотите удалить эту группу? Участники потеряют доступ к материалам, к которым у этой группы есть доступ.",
   "Are you sure you want to delete this page?": "Вы уверены, что хотите удалить эту страницу?",
   "Are you sure you want to remove this user from the group? The user will lose access to resources this group has access to.": "Вы уверены, что хотите удалить этого пользователя из группы? Пользователь потеряет доступ к материалам, к которым есть доступ у этой группы.",
   "Are you sure you want to remove this user from the space? The user will lose all access to this space.": "Вы уверены, что хотите удалить этого пользователя из пространства? Пользователь потеряет весь доступ к этому пространству.",
   "Are you sure you want to restore this version? Any changes not versioned will be lost.": "Вы уверены, что хотите восстановить эту версию? Все не зафиксированные изменения будут потеряны.",
+  "Are you sure you want to revoke \"{{name}}\"? Any client using this key will immediately lose access. This cannot be undone.": "Вы уверены, что хотите отозвать «{{name}}»? Любой клиент, использующий этот ключ, немедленно потеряет доступ. Это действие нельзя отменить.",
+  "Author": "Автор",
   "Can become members of groups and spaces in workspace": "Могут становиться участниками групп и пространств в рабочей области",
   "Can create and edit pages in space.": "Может создавать и редактировать страницы в пространстве.",
   "Can edit": "Может изменять",
@@ -32,7 +41,9 @@
   "Confirm": "Подтвердить",
   "Copy as Markdown": "Копировать как Markdown",
   "Copy link": "Копировать ссылку",
+  "Copy your API key now and store it somewhere safe. For security reasons it will not be shown again.": "Скопируйте API ключ сейчас и сохраните его в надёжном месте. В целях безопасности он больше не будет показан.",
   "Create": "Создать",
+  "Create API key": "Создать API ключ",
   "Create group": "Создать группу",
   "Create page": "Создать страницу",
   "Create space": "Создать пространство",
@@ -45,6 +56,7 @@
   "Are you sure you want to delete this page? This will delete its children and page history. This action is irreversible.": "Вы уверены, что хотите удалить эту страницу? Это удалит её дочерние страницы, а также историю страницы. Это действие необратимо.",
   "Description": "Описание",
   "Details": "Подробности",
+  "Done": "Готово",
   "e.g ACME": "например, ACME",
   "e.g ACME Inc": "например, ACME Inc",
   "e.g Developers": "например, Developers",
@@ -54,7 +66,15 @@
   "e.g Sales": "например, Sales",
   "e.g Space for product team": "например, Пространство для команды продукта",
   "e.g Space for sales team to collaborate": "например, Пространство для совместной работы команды продаж",
+  "e.g. CI deploy token": "например, токен деплоя CI",
   "Edit": "Редактировать",
+  "Expiring soon": "Скоро истекает",
+  "Failed to create API key": "Не удалось создать API ключ",
+  "Failed to load API keys.": "Не удалось загрузить API ключи.",
+  "Failed to revoke API key": "Не удалось отозвать API ключ",
+  "Name is required": "Имя обязательно",
+  "Never used": "Не использовался",
+  "No API keys yet": "Пока нет API ключей",
   "Read": "Чтение",
   "Edit group": "Редактировать группу",
   "Email": "Электронная почта",
@@ -133,6 +153,8 @@
   "page": "страница",
   "Page deleted successfully": "Страница успешно удалена",
   "Page history": "История страницы",
+  "Revoke API key": "Отозвать API ключ",
+  "Revoke {{name}}": "Отозвать {{name}}",
   "Select version": "Выбрать версию",
   "Highlight changes": "Выделить изменения",
   "Page import is in progress. Please do not close this tab.": "Импорт страницы в процессе. Пожалуйста, не закрывайте эту вкладку.",
@@ -188,6 +210,9 @@
   "Template": "Шаблон",
   "Templates": "Шаблоны",
   "Theme": "Тема",
+  "This key expires within 30 days": "Этот ключ истекает в течение 30 дней",
+  "This key has expired": "Этот ключ истек",
+  "This key never expires": "Этот ключ никогда не истекает",
   "To change your email, you have to enter your password and new email.": "Чтобы изменить электронную почту, вам нужно ввести пароль и новый адрес.",
   "Toggle full page width": "Переключить полную ширину страницы",
   "Unable to import pages. Please try again.": "Не удалось импортировать страницы. Пожалуйста, попробуйте ещё раз.",
@@ -195,6 +220,7 @@
   "Untitled": "Без названия",
   "Updated successfully": "Успешно обновлено",
   "User": "Пользователь",
+  "Within the last hour": "За последний час",
   "Workspace": "Рабочее пространство",
   "Workspace Name": "Название рабочего пространства",
   "Workspace settings": "Настройки рабочего пространства",
@@ -239,6 +265,8 @@
   "Comment re-opened successfully": "Комментарий успешно открыт повторно",
   "Comment unresolved successfully": "Комментарий успешно переведён в нерешённые",
   "Failed to resolve comment": "Не удалось разрешить комментарий",
+  "Failed to re-open comment": "Не удалось переоткрыть комментарий",
+  "Comment no longer exists": "Комментарий больше не существует",
   "Resolve comment": "Решить комментарий",
   "Unresolve comment": "Снять статус решённого с комментария",
   "Resolve Comment Thread": "Решить ветку комментариев",
@@ -429,6 +457,7 @@
   "Write anything. Enter \"/\" for commands": "Пишите что угодно. Введите \"/\" для команд",
   "Write...": "Напишите...",
   "Column count": "Количество столбцов",
+  "Your personal API keys.": "Ваши личные API ключи.",
   "{{count}} Columns": "{count, plural, one{# столбец} few{# столбца} many{# столбцов} other{# столбца}}",
   "{{count}} command available_one": "Доступна 1 команда",
   "{{count}} command available_other": "Доступно {{count}} команд",
@@ -1442,5 +1471,21 @@
   "Boundary": "Граница",
   "Autosave": "Автосейв",
   "Only versions": "Только версии",
-  "No saved versions yet.": "Пока нет сохранённых версий."
+  "No saved versions yet.": "Пока нет сохранённых версий.",
+  "Time worked on this article": "Время работы над статьёй",
+  "Show time worked on this page": "Показать время работы над страницей",
+  "Estimated time worked (inactivity gap {{gap}} min)": "Оценка времени работы (порог паузы {{gap}} мин)",
+  "Estimate · timezone {{tz}} · inactivity gap {{gap}} min": "Оценка · таймзона {{tz}} · порог паузы {{gap}} мин",
+  "No editing activity recorded yet.": "Правок пока нет.",
+  "× {{count}} days without edits": "× {{count}} дн. без правок",
+  "agent: {{value}}": "агент: {{value}}",
+  "Work": "Работа",
+  "Agent": "Агент",
+  "{{start}} – {{end}} · {{duration}}": "{{start}} – {{end}} · {{duration}}",
+  "≈ {{hours}}h {{minutes}}m": "≈ {{hours}} ч {{minutes}} мин",
+  "≈ {{hours}}h": "≈ {{hours}} ч",
+  "≈ {{minutes}}m": "≈ {{minutes}} мин",
+  "{{hours}}h {{minutes}}m": "{{hours}} ч {{minutes}} м",
+  "{{hours}}h": "{{hours}} ч",
+  "{{minutes}}m": "{{minutes}} м"
 }

apps/client/src/App.tsx

@@ -44,6 +44,12 @@ const AccountSettings = lazy(
 const AccountPreferences = lazy(
   () => import("@/pages/settings/account/account-preferences.tsx"),
 );
+// #506 — lazy leaf (own chunk): the API-keys management page is route-split so
+// its code (Mantine table/modals + the create/revoke flow) stays out of the
+// entry bundle (post-#342 bundle discipline).
+const AccountApiKeys = lazy(
+  () => import("@/pages/settings/account/account-api-keys.tsx"),
+);
 const WorkspaceSettings = lazy(
   () => import("@/pages/settings/workspace/workspace-settings"),
 );
@@ -105,6 +111,7 @@ export default function App() {
               path={"account/preferences"}
               element={<AccountPreferences />}
             />
+            <Route path={"account/api-keys"} element={<AccountApiKeys />} />
             <Route path={"workspace"} element={<WorkspaceSettings />} />
             <Route path={"ai"} element={<AiSettings />} />
             <Route path={"members"} element={<WorkspaceMembers />} />

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

@@ -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);
-  });
-});

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

@@ -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();
 }
 

apps/client/src/components/settings/settings-sidebar.tsx

@@ -10,6 +10,7 @@ import {
   IconBrush,
   IconWorld,
   IconSparkles,
+  IconKey,
 } from "@tabler/icons-react";
 import { Link, useLocation } from "react-router-dom";
 import classes from "./settings.module.css";
@@ -46,6 +47,11 @@ const groupedData: DataGroup[] = [
         icon: IconBrush,
         path: "/settings/account/preferences",
       },
+      {
+        label: "API keys",
+        icon: IconKey,
+        path: "/settings/account/api-keys",
+      },
     ],
   },
   {

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

@@ -27,6 +27,7 @@ vi.mock("@/features/ai-chat/utils/markdown.ts", async () => {
 
 import MessageItem from "./message-item";
 import { messageSignature } from "@/features/ai-chat/utils/message-signature.ts";
+import { splitPlainChunks } from "./streaming-plain-text";
 
 // matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
 
@@ -114,3 +115,89 @@ describe("MessageItem markdown memoization", () => {
     expect(queryByText("streamed answer")).not.toBeNull();
   });
 });
+
+// PERF SMOKE (#492): the whole point of the incremental streaming render is that
+// the ANSWER path costs O(number of markdown blocks), NOT O(number of throttled
+// ~20Hz ticks). Pre-#492 the finalized MarkdownPart re-parsed the WHOLE growing
+// answer on every delta — a synthetic ~100 KB stream measured 394 renderChatMarkdown
+// calls (one per tick). With the incremental render each STABILIZED block is parsed
+// exactly once (memoized in MarkdownChunk) and the live tail is cheap plain text, so
+// the call count collapses to ~= the block count regardless of tick granularity.
+describe("MessageItem streaming answer render is O(blocks), not O(ticks)", () => {
+  // ~100 KB answer. Each section is a heading + a paragraph — TWO blank-line
+  // delimited markdown blocks — so the safe-cut block count is ~2× the section
+  // count. The perf claim is about the BLOCK count (the memoization granularity),
+  // measured directly with splitPlainChunks below, not the section count.
+  const buildAnswer = () => {
+    const SECTIONS = 100;
+    const paragraphs: string[] = [];
+    for (let i = 0; i < SECTIONS; i++) {
+      paragraphs.push(`## Section ${i}\n\n` + "lorem ipsum dolor ".repeat(55));
+    }
+    const full = paragraphs.join("\n\n");
+    // The number of memoized markdown blocks the incremental render splits into
+    // (all but the live tail are parsed once each).
+    return { full, blocks: splitPlainChunks(full).length };
+  };
+
+  const streamMsg = (text: string, state: "streaming" | "done"): UIMessage =>
+    ({
+      id: "m1",
+      role: "assistant",
+      parts: [{ type: "text", text, state }],
+    }) as UIMessage;
+
+  it("parses each block ~once over a 100KB stream (≈blocks, ≪ ticks)", () => {
+    renderChatMarkdownSpy.mockClear();
+    const { full, blocks } = buildAnswer();
+    const CHUNK = 128; // a realistic ~20Hz throttled delta size
+    const ticks = Math.ceil(full.length / CHUNK);
+
+    let msg = streamMsg(full.slice(0, CHUNK), "streaming");
+    const { rerender } = render(
+      <MantineProvider>
+        <MessageItem
+          message={msg}
+          signature={messageSignature(msg)}
+          turnStreaming
+        />
+      </MantineProvider>,
+    );
+    for (let end = 2 * CHUNK; end < full.length; end += CHUNK) {
+      msg = streamMsg(full.slice(0, end), "streaming");
+      rerender(
+        <MantineProvider>
+          <MessageItem
+            message={msg}
+            signature={messageSignature(msg)}
+            turnStreaming
+          />
+        </MantineProvider>,
+      );
+    }
+    // Finalize: the streaming→done flip renders the whole answer through ONE
+    // canonical pass (visual parity), so the finished DOM matches the pre-#492
+    // output. This is the single extra parse on top of the per-block ones.
+    const done = streamMsg(full, "done");
+    rerender(
+      <MantineProvider>
+        <MessageItem message={done} signature={messageSignature(done)} />
+      </MantineProvider>,
+    );
+
+    const calls = renderChatMarkdownSpy.mock.calls.length;
+    // Sanity: the stream really had far more ticks than blocks (else the test is
+    // vacuous — the point is that calls scale with blocks, not ticks).
+    expect(ticks).toBeGreaterThan(blocks * 3);
+    // O(blocks): each stabilized block parsed once + the single final whole-text
+    // parse. A small constant absorbs the finalize render and the live-tail block;
+    // the load-bearing claim is the bound below.
+    expect(calls).toBeLessThanOrEqual(blocks + 2);
+    // ≪ ticks — and, non-vacuously, the blocks WERE parsed (not skipped entirely).
+    expect(calls).toBeLessThan(ticks / 3);
+    expect(calls).toBeGreaterThan(blocks / 2);
+    // MUTATION-VERIFY (documented, not run here): dropping the `memo()` wrapper on
+    // MarkdownChunk (so every stable block re-parses each tick) drives `calls`
+    // toward `ticks` (~394), reddening both upper-bound assertions above.
+  });
+});

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

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from "vitest";
+import { render } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import type { UIMessage } from "@ai-sdk/react";
+
+// Stub react-i18next (the component reads `useTranslation`). Mirrors the other
+// message-item specs.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+import MessageItem from "./message-item";
+import { messageSignature } from "@/features/ai-chat/utils/message-signature.ts";
+// The REAL canonical renderer (NOT the spy the memo test installs): this file
+// exercises the actual markdown output so the visual-regression assertions below
+// compare against genuine HTML (incl. the schema's `<li><p>` wrappers).
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
+import classes from "./ai-chat.module.css";
+
+const msg = (
+  parts: UIMessage["parts"],
+  extra?: Partial<UIMessage>,
+): UIMessage =>
+  ({ id: "m1", role: "assistant", parts, ...extra }) as UIMessage;
+
+const renderRow = (message: UIMessage, turnStreaming = false) =>
+  render(
+    <MantineProvider>
+      <MessageItem
+        message={message}
+        signature={messageSignature(message)}
+        turnStreaming={turnStreaming}
+      />
+    </MantineProvider>,
+  );
+
+// A rich multi-block answer that exercises headings, a list (the `<li><p>` case
+// the scoped CSS tightens), inline emphasis, and multiple paragraphs.
+const ANSWER = [
+  "# Заголовок",
+  "",
+  "Первый абзац с **жирным** и `кодом`.",
+  "",
+  "- пункт один",
+  "- пункт два",
+  "",
+  "Второй абзац.",
+].join("\n");
+
+describe("MessageItem final render — visual parity with the canonical pipeline", () => {
+  it("a finalized text part renders exactly renderChatMarkdown(text)", () => {
+    const { container } = renderRow(
+      msg([{ type: "text", text: ANSWER, state: "done" }]),
+    );
+    const block = container.querySelector(`.${classes.markdown}`);
+    expect(block).not.toBeNull();
+    // Byte-for-byte the canonical output (the SAME whole-text pass the pre-#492
+    // MarkdownPart produced), including `<li><p>…</p></li>` wrappers.
+    expect(block!.innerHTML).toBe(renderChatMarkdown(ANSWER, {}));
+    // The list wrapper is really present (guards against a vacuous empty render).
+    expect(container.querySelectorAll("li p").length).toBe(2);
+  });
+
+  it("the streaming incremental view CONVERGES to the canonical render on finish", () => {
+    // Mount mid-stream (live tail) — the DOM here is the incremental view.
+    const { container, rerender } = render(
+      <MantineProvider>
+        <MessageItem
+          message={msg([{ type: "text", text: ANSWER, state: "streaming" }])}
+          signature={messageSignature(
+            msg([{ type: "text", text: ANSWER, state: "streaming" }]),
+          )}
+          turnStreaming
+        />
+      </MantineProvider>,
+    );
+    // Finish the turn: state flips to done AND the turn is no longer streaming.
+    const done = msg([{ type: "text", text: ANSWER, state: "done" }]);
+    rerender(
+      <MantineProvider>
+        <MessageItem message={done} signature={messageSignature(done)} />
+      </MantineProvider>,
+    );
+    // After finish there is exactly ONE canonical markdown container whose HTML is
+    // the whole-text render — identical to the non-streaming path above.
+    const blocks = container.querySelectorAll(`.${classes.markdown}`);
+    expect(blocks.length).toBe(1);
+    expect(blocks[0].innerHTML).toBe(renderChatMarkdown(ANSWER, {}));
+  });
+
+  it("neutralizeInternalLinks is honored on the finalized render", () => {
+    const linkAnswer = "См. [страницу](/p/abc).";
+    const { container } = render(
+      <MantineProvider>
+        <MessageItem
+          message={msg([{ type: "text", text: linkAnswer, state: "done" }])}
+          signature={messageSignature(
+            msg([{ type: "text", text: linkAnswer, state: "done" }]),
+          )}
+          neutralizeInternalLinks
+        />
+      </MantineProvider>,
+    );
+    const block = container.querySelector(`.${classes.markdown}`);
+    expect(block!.innerHTML).toBe(
+      renderChatMarkdown(linkAnswer, { neutralizeInternalLinks: true }),
+    );
+    // The internal link was made inert (no href) by the neutralization flag.
+    const a = container.querySelector("a");
+    expect(a?.hasAttribute("href")).toBe(false);
+  });
+});

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

@@ -4,6 +4,7 @@ import { useTranslation } from "react-i18next";
 import type { UIMessage } from "@ai-sdk/react";
 import ToolCallCard from "@/features/ai-chat/components/tool-call-card.tsx";
 import ReasoningBlock from "@/features/ai-chat/components/reasoning-block.tsx";
+import { StreamingMarkdownText } from "@/features/ai-chat/components/streaming-markdown-text.tsx";
 import ChatErrorAlert from "@/features/ai-chat/components/chat-error-alert.tsx";
 import ChatStoppedNotice from "@/features/ai-chat/components/chat-stopped-notice.tsx";
 import { ToolUiPart, isToolPart } from "@/features/ai-chat/utils/tool-parts.tsx";
@@ -86,17 +87,39 @@ interface MessageItemProps {
  * One assistant text part rendered as sanitized markdown. Memoized on its inputs
  * so a finalized text part is NOT re-parsed on every streamed delta: during a
  * turn only the actively-growing tail part changes its `text`, so every earlier
- * part hits the memo and skips the expensive marked + DOMPurify pass. Props are
- * primitives, so React.memo's default shallow compare is exactly right (the
- * `text` string is compared by value).
+ * part hits the memo and skips the expensive canonical parse + DOMPurify pass.
+ * Props are primitives, so React.memo's default shallow compare is exactly right
+ * (the `text` string is compared by value).
+ *
+ * Streaming gate (#492) — mirrors ReasoningBlock:
+ *  - `streaming` (this is the live, actively-growing tail part of an in-flight
+ *    turn): render incrementally via StreamingMarkdownText — the stabilized blocks
+ *    go through the canonical pipeline (each parsed ONCE, memoized) and only the
+ *    live tail is cheap plain text. This makes the per-tick cost O(new blocks),
+ *    not the pre-#492 O(ticks) whole-answer re-parse on every ~20Hz delta.
+ *  - finalized (the common case, and the turn-end flip): render the WHOLE text
+ *    through ONE canonical pass — byte-identical to the pre-#492 output (visual
+ *    parity). The row re-renders on the streaming→done flip because
+ *    `messageSignature` tracks each part's `state` (and `turnStreaming` flips at
+ *    turn end), so the incremental view always converges to this single render.
  */
 const MarkdownPart = memo(function MarkdownPart({
   text,
   neutralizeInternalLinks,
+  streaming,
 }: {
   text: string;
   neutralizeInternalLinks: boolean;
+  streaming: boolean;
 }) {
+  if (streaming) {
+    return (
+      <StreamingMarkdownText
+        text={text}
+        neutralizeInternalLinks={neutralizeInternalLinks}
+      />
+    );
+  }
   const html = renderChatMarkdown(text, { neutralizeInternalLinks });
   if (html) {
     return (
@@ -179,47 +202,10 @@ function MessageItem({
         {resolveAssistantName(assistantName) ?? t("AI agent")}
       </Text>
       {message.parts.map((part, index) => {
-        if (part.type === "reasoning") {
-          // Reasoning ("thinking") -> a collapsible block with its own token
-          // count. Empty/whitespace reasoning with no authoritative count carries
-          // nothing to show, so skip it (avoids an empty 0-token block).
-          const text = (part as { text?: string }).text ?? "";
-          if (!text.trim() && !(reasoningTokens && reasoningTokens > 0))
-            return null;
-          // Absent state (persisted rows) and "done" both mean finalized.
-          // `messageSignature` already includes each part's `state`, so the
-          // streaming→done flip changes the row signature and re-renders this
-          // row — which is what lets ReasoningBlock switch from chunked plain
-          // text to its one-time markdown parse (see reasoning-block.tsx).
-          // ALSO require the turn to be live: a part stranded at
-          // `state:"streaming"` after the turn ended (no `reasoning-end` — see
-          // the `turnStreaming` prop doc) must still finalize and parse.
-          const streaming =
-            turnStreaming && (part as { state?: string }).state === "streaming";
-          return (
-            <ReasoningBlock
-              key={index}
-              text={text}
-              tokens={reasoningTokens}
-              streaming={streaming}
-            />
-          );
-        }
-
-        if (part.type === "text") {
-          // Skip empty/whitespace-only text parts (a streaming message often
-          // starts with an empty text part before the first token arrives); the
-          // typing indicator covers that gap until real content streams in.
-          if (!part.text.trim()) return null;
-          return (
-            <MarkdownPart
-              key={index}
-              text={part.text}
-              neutralizeInternalLinks={neutralizeInternalLinks}
-            />
-          );
-        }
-
+        // Tool parts (`tool-*` / `dynamic-tool`) are template-literal kinds, so
+        // they cannot be a `switch` case; the runtime guard handles them, and the
+        // switch below covers every CLOSED (literal-typed) part kind with a
+        // compile-time exhaustiveness check in its default.
         if (isToolPart(part.type)) {
           return (
             <ToolCallCard
@@ -232,7 +218,76 @@ function MessageItem({
           );
         }
 
-        return null;
+        switch (part.type) {
+          case "reasoning": {
+            // Reasoning ("thinking") -> a collapsible block with its own token
+            // count. Empty/whitespace reasoning with no authoritative count
+            // carries nothing to show, so skip it (avoids an empty 0-token block).
+            const text = part.text ?? "";
+            if (!text.trim() && !(reasoningTokens && reasoningTokens > 0))
+              return null;
+            // Absent state (persisted rows) and "done" both mean finalized.
+            // `messageSignature` already includes each part's `state`, so the
+            // streaming→done flip changes the row signature and re-renders this
+            // row — which is what lets ReasoningBlock switch from chunked plain
+            // text to its one-time markdown parse (see reasoning-block.tsx).
+            // ALSO require the turn to be live: a part stranded at
+            // `state:"streaming"` after the turn ended (no `reasoning-end` — see
+            // the `turnStreaming` prop doc) must still finalize and parse.
+            const streaming = turnStreaming && part.state === "streaming";
+            return (
+              <ReasoningBlock
+                key={index}
+                text={text}
+                tokens={reasoningTokens}
+                streaming={streaming}
+              />
+            );
+          }
+
+          case "text": {
+            // Skip empty/whitespace-only text parts (a streaming message often
+            // starts with an empty text part before the first token arrives); the
+            // typing indicator covers that gap until real content streams in.
+            if (!part.text.trim()) return null;
+            // The live, actively-growing tail part of the in-flight turn renders
+            // incrementally (see MarkdownPart); a finalized part (persisted, or
+            // the turn-end flip) renders the whole text through one canonical
+            // pass. Same liveness rule as the reasoning branch above.
+            const streaming = turnStreaming && part.state === "streaming";
+            return (
+              <MarkdownPart
+                key={index}
+                text={part.text}
+                neutralizeInternalLinks={neutralizeInternalLinks}
+                streaming={streaming}
+              />
+            );
+          }
+
+          case "source-url":
+          case "source-document":
+          case "file":
+          case "step-start":
+            // Not surfaced in the chat bubble (v1) — same as the pre-#492 default.
+            return null;
+
+          default: {
+            // Compile-time exhaustiveness over the CLOSED union members: every
+            // literal-typed part kind is handled above, so the only kinds that
+            // can reach here are the OPEN template-literal ones (`tool-*` — caught
+            // by the guard at runtime — and `data-*`) plus `dynamic-tool`. Adding
+            // a NEW closed part kind to UIMessagePart makes this assignment fail
+            // to compile, forcing it to be handled instead of silently ignored
+            // (this replaces the pre-#492 fall-through `return null` + WARNING).
+            const _exhaustive:
+              | `tool-${string}`
+              | "dynamic-tool"
+              | `data-${string}` = part.type;
+            void _exhaustive;
+            return null;
+          }
+        }
       })}
       {/* A persisted turn error (server stored it in metadata.error). Rendered
           here so it survives a thread remount and shows in reopened history. */}

apps/client/src/features/ai-chat/components/streaming-markdown-text.tsx

@@ -0,0 +1,96 @@
+import { memo, useMemo } from "react";
+import { splitPlainChunks } from "@/features/ai-chat/components/streaming-plain-text.tsx";
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
+import classes from "@/features/ai-chat/components/ai-chat.module.css";
+
+/**
+ * One STABILIZED markdown block, rendered through the canonical pipeline and
+ * memoized on its string prop. During streaming only the TAIL chunk grows (the
+ * `splitPlainChunks` append-only invariant guarantees every earlier chunk is
+ * byte-identical across deltas), so React skips every stable block and each one
+ * is parsed by `renderChatMarkdown` EXACTLY ONCE — turning the pre-#492
+ * "re-parse the whole accumulated answer on every ~20Hz tick" (O(ticks)) into
+ * O(number of blocks). The markup is DOMPurify-sanitized inside renderChatMarkdown
+ * before it reaches `dangerouslySetInnerHTML`.
+ *
+ * NOTE (transient streaming-only artifact): a safe cut is a blank-line boundary,
+ * so a construct that legitimately contains a blank line (e.g. a fenced code block
+ * with an empty line) can be split across chunks and render oddly WHILE it is still
+ * streaming. This is cosmetic and self-heals: the moment the part finalizes,
+ * MarkdownPart renders the WHOLE text through one canonical pass (visual parity
+ * with the pre-#492 output). The reasoning path makes the same trade (plain text
+ * while streaming, one markdown parse at the end).
+ */
+const MarkdownChunk = memo(function MarkdownChunk({
+  text,
+  neutralizeInternalLinks,
+}: {
+  text: string;
+  neutralizeInternalLinks: boolean;
+}) {
+  const html = renderChatMarkdown(text, { neutralizeInternalLinks });
+  if (html) {
+    return (
+      <div
+        className={classes.markdown}
+        // Sanitized by renderChatMarkdown (DOMPurify) before insertion.
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    );
+  }
+  // Malformed/unsupported markdown could not render synchronously: raw text.
+  return (
+    <div className={classes.markdown} style={{ whiteSpace: "pre-wrap" }}>
+      {text}
+    </div>
+  );
+});
+
+/**
+ * The cheap streaming-time stand-in for the finalized answer's one-time markdown
+ * parse (see MarkdownPart in message-item.tsx). Mirrors StreamingPlainText's
+ * chunked-memo pattern but renders the STABILIZED prefix as real markdown (each
+ * block parsed once, memoized) and only the LIVE tail as flat plain text — so the
+ * user sees formatted output for everything up to the last safe cut, and the not-
+ * yet-stable tail (which markdown-parsing every tick would make O(ticks)) stays a
+ * single cheap escaped text node until it stabilizes into a new block.
+ *
+ * `splitPlainChunks` yields chunks where, under append-only growth, every chunk
+ * except the LAST is immutable; the last chunk is the live tail. Index keys are
+ * therefore stable (a given index never changes to a different chunk's content).
+ */
+export function StreamingMarkdownText({
+  text,
+  neutralizeInternalLinks,
+}: {
+  text: string;
+  neutralizeInternalLinks: boolean;
+}) {
+  const chunks = useMemo(() => splitPlainChunks(text), [text]);
+  return (
+    <>
+      {chunks.map((chunk, index) =>
+        index < chunks.length - 1 ? (
+          <MarkdownChunk
+            key={index}
+            text={chunk}
+            neutralizeInternalLinks={neutralizeInternalLinks}
+          />
+        ) : (
+          // The live tail: flat, React-escaped plain text (no markdown parse, no
+          // sanitizer, no innerHTML). `pre-wrap` preserves its newlines; trailing
+          // separator newlines are dropped at display time so the block gap comes
+          // from the markdown margins, not a doubled empty line (mirrors
+          // PlainChunk in streaming-plain-text.tsx).
+          <div
+            key={index}
+            className={classes.markdown}
+            style={{ whiteSpace: "pre-wrap" }}
+          >
+            {chunk.replace(/\n+$/, "")}
+          </div>
+        ),
+      )}
+    </>
+  );
+}

apps/client/src/features/api-key/components/api-keys-manager.test.tsx

@@ -0,0 +1,234 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  render,
+  screen,
+  fireEvent,
+  waitFor,
+  within,
+} from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { ModalsProvider } from "@mantine/modals";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Provider, createStore } from "jotai";
+import { UserRole } from "@/lib/types";
+import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
+import { IApiKey } from "@/features/api-key/types/api-key.types";
+
+// Mock the service layer so no real HTTP is attempted; every test drives the
+// component through these three functions.
+vi.mock("@/features/api-key/services/api-key-service", () => ({
+  getApiKeys: vi.fn(),
+  createApiKey: vi.fn(),
+  revokeApiKey: vi.fn(),
+}));
+
+import {
+  getApiKeys,
+  createApiKey,
+  revokeApiKey,
+} from "@/features/api-key/services/api-key-service";
+import ApiKeysManager from "./api-keys-manager";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+const ISO_SOON = new Date(Date.now() + 10 * 864e5).toISOString();
+const ISO_FAR = new Date(Date.now() + 200 * 864e5).toISOString();
+const ISO_EXPIRED = new Date(Date.now() - 3 * 864e5).toISOString();
+
+// Dump the storage stub via the Web Storage API — its data lives in a closure
+// (see vitest.setup.ts), so JSON.stringify(localStorage) would be vacuous.
+function storageDump(): string {
+  let out = "";
+  for (let i = 0; i < localStorage.length; i++) {
+    const k = localStorage.key(i) as string;
+    out += `${k}=${localStorage.getItem(k)};`;
+  }
+  return out;
+}
+
+function makeKey(overrides: Partial<IApiKey> = {}): IApiKey {
+  return {
+    id: "key-1",
+    name: "CI token",
+    expiresAt: ISO_FAR,
+    lastUsedAt: null,
+    createdAt: "2026-01-01T00:00:00.000Z",
+    creator: { id: "u1", name: "Alice", email: "a@x.io", avatarUrl: null },
+    ...overrides,
+  };
+}
+
+function renderManager(role: UserRole) {
+  const store = createStore();
+  store.set(currentUserAtom, {
+    user: { id: "me", role } as never,
+    workspace: {} as never,
+  });
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const utils = render(
+    <Provider store={store}>
+      <QueryClientProvider client={queryClient}>
+        <MantineProvider>
+          <ModalsProvider>
+            <ApiKeysManager />
+          </ModalsProvider>
+        </MantineProvider>
+      </QueryClientProvider>
+    </Provider>,
+  );
+  return { store, queryClient, ...utils };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  localStorage.clear();
+});
+
+describe("ApiKeysManager — list rendering", () => {
+  it("renders an explicit expiry date and highlights a <30-day key (acceptance #3)", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ id: "k-soon", name: "Soon key", expiresAt: ISO_SOON }),
+      makeKey({ id: "k-far", name: "Far key", expiresAt: ISO_FAR }),
+    ]);
+
+    renderManager(UserRole.MEMBER);
+
+    await screen.findByText("Soon key");
+    // Explicit dates, not "in N days": the year is rendered verbatim.
+    const soonYear = new Date(ISO_SOON).getFullYear().toString();
+    expect(screen.getAllByText(new RegExp(soonYear)).length).toBeGreaterThan(0);
+    // Exactly one key is inside the 30-day warning window.
+    expect(screen.getAllByText("Expiring soon")).toHaveLength(1);
+  });
+
+  it('shows "Expired" (not "Expiring soon") for an already-expired key', async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ id: "k-dead", name: "Dead key", expiresAt: ISO_EXPIRED }),
+    ]);
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("Dead key");
+    // A past expiry is labelled "Expired", never the forward-looking badge.
+    expect(screen.getByText("Expired")).toBeDefined();
+    expect(screen.queryByText("Expiring soon")).toBeNull();
+  });
+
+  it('shows "Never" for an unlimited key and no highlight', async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ id: "k-forever", name: "Forever", expiresAt: null }),
+    ]);
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("Forever");
+    expect(screen.getByText("Never")).toBeDefined();
+    expect(screen.queryByText("Expiring soon")).toBeNull();
+  });
+
+  it("empty list shows the empty state", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([]);
+    renderManager(UserRole.MEMBER);
+    expect(await screen.findByText("No API keys yet")).toBeDefined();
+  });
+});
+
+describe("ApiKeysManager — admin vs member view (acceptance #6)", () => {
+  it("a member does NOT see the author column", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ creator: { id: "me", name: "Me", email: "m@x.io", avatarUrl: null } }),
+    ]);
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("CI token");
+    // Author header absent + creator name not rendered (no author column).
+    expect(screen.queryByText("Author")).toBeNull();
+    expect(screen.queryByText("Me")).toBeNull();
+  });
+
+  it("an admin sees the author column with the creator's name", async () => {
+    vi.mocked(getApiKeys).mockResolvedValue([
+      makeKey({ creator: { id: "u1", name: "Alice", email: "a@x.io", avatarUrl: null } }),
+    ]);
+    renderManager(UserRole.ADMIN);
+    await screen.findByText("CI token");
+    expect(screen.getByText("Author")).toBeDefined();
+    expect(screen.getByText("Alice")).toBeDefined();
+  });
+});
+
+describe("ApiKeysManager — revoke (acceptance #4)", () => {
+  it("revoke removes the row from the list", async () => {
+    vi.mocked(getApiKeys)
+      .mockResolvedValueOnce([
+        makeKey({ id: "k1", name: "Doomed" }),
+        makeKey({ id: "k2", name: "Survivor" }),
+      ])
+      // After revoke, invalidation refetches the reduced list.
+      .mockResolvedValue([makeKey({ id: "k2", name: "Survivor" })]);
+    vi.mocked(revokeApiKey).mockResolvedValue();
+
+    renderManager(UserRole.MEMBER);
+    await screen.findByText("Doomed");
+
+    fireEvent.click(screen.getByLabelText("Revoke Doomed"));
+    // Confirm modal → click the destructive confirm button.
+    const confirm = await screen.findByRole("button", { name: "Revoke" });
+    fireEvent.click(confirm);
+
+    await waitFor(() =>
+      expect(screen.queryByText("Doomed")).toBeNull(),
+    );
+    expect(screen.getByText("Survivor")).toBeDefined();
+    expect(revokeApiKey).toHaveBeenCalledWith("k1");
+  });
+});
+
+describe("ApiKeysManager — show-once token (acceptance #1 & #2)", () => {
+  it("shows the token once, then discards it from the UI, localStorage and query cache", async () => {
+    const SECRET = "gm_secret-token-value-xyz";
+    vi.mocked(getApiKeys).mockResolvedValue([]);
+    vi.mocked(createApiKey).mockResolvedValue({
+      token: SECRET,
+      apiKey: {
+        id: "new-1",
+        name: "My key",
+        expiresAt: ISO_FAR,
+        createdAt: new Date().toISOString(),
+      },
+    });
+
+    const { queryClient } = renderManager(UserRole.MEMBER);
+    await screen.findByText("No API keys yet");
+
+    // Open create modal (use the header CTA), fill the name, submit.
+    fireEvent.click(
+      screen.getAllByRole("button", { name: "Create API key" })[0],
+    );
+    const nameInput = await screen.findByLabelText(/Name/);
+    fireEvent.change(nameInput, { target: { value: "My key" } });
+    fireEvent.click(screen.getByRole("button", { name: "Create" }));
+
+    // Token is shown exactly once in the show-once modal.
+    const tokenEl = await screen.findByTestId("api-key-token");
+    expect(tokenEl.textContent).toBe(SECRET);
+
+    // Close the modal → token discarded from the DOM.
+    fireEvent.click(screen.getByRole("button", { name: "Done" }));
+    await waitFor(() =>
+      expect(screen.queryByTestId("api-key-token")).toBeNull(),
+    );
+
+    // Acceptance #2: the secret is nowhere in localStorage or the react-query
+    // caches (query cache never carried it; the mutation copy was reset()).
+    // Non-vacuous: currentUser IS in storage, so the dump is exercised.
+    const dump = storageDump();
+    expect(dump).toContain("currentUser");
+    expect(dump).not.toContain(SECRET);
+    const cacheDump = JSON.stringify(
+      queryClient.getQueryCache().getAll().map((q) => q.state.data),
+    );
+    expect(cacheDump).not.toContain(SECRET);
+    const mutationDump = JSON.stringify(
+      queryClient.getMutationCache().getAll().map((m) => m.state.data),
+    );
+    expect(mutationDump).not.toContain(SECRET);
+  });
+});

apps/client/src/features/api-key/components/api-keys-manager.tsx

@@ -0,0 +1,264 @@
+import { useState } from "react";
+import {
+  ActionIcon,
+  Badge,
+  Button,
+  Center,
+  Group,
+  Loader,
+  Stack,
+  Table,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import { modals } from "@mantine/modals";
+import { notifications } from "@mantine/notifications";
+import { IconAlertTriangle, IconKey, IconTrash } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import useUserRole from "@/hooks/use-user-role.tsx";
+import { formatLocalized, useDateFnsLocale } from "@/lib/date-locale";
+import { timeAgo } from "@/lib/time";
+import {
+  useApiKeysQuery,
+  useCreateApiKeyMutation,
+  useRevokeApiKeyMutation,
+} from "@/features/api-key/queries/api-key-query";
+import {
+  IApiKey,
+  ICreateApiKeyResponse,
+} from "@/features/api-key/types/api-key.types";
+import {
+  isExpired,
+  isExpiringSoon,
+  lastUsedBucket,
+} from "@/features/api-key/utils";
+import { CreateApiKeyModal } from "./create-api-key-modal";
+import { ShowTokenModal } from "./show-token-modal";
+
+export default function ApiKeysManager() {
+  const { t } = useTranslation();
+  const locale = useDateFnsLocale();
+  // Manage-on-API === Owner/Admin server-side, so the admin (workspace-wide)
+  // list + "author" column mirror exactly the roles the server serves the
+  // whole-workspace response to.
+  const { isAdmin } = useUserRole();
+
+  const { data: keys, isLoading, isError } = useApiKeysQuery();
+  const createMutation = useCreateApiKeyMutation();
+  const revokeMutation = useRevokeApiKeyMutation();
+
+  const [createOpened, setCreateOpened] = useState(false);
+  // SECURITY: the show-once token lives ONLY here, in this component's local
+  // state. It is never written to localStorage, the query cache or a log. Closing
+  // the modal sets it back to null (handleCloseToken) — discarded forever.
+  const [createdKey, setCreatedKey] = useState<ICreateApiKeyResponse | null>(
+    null,
+  );
+
+  const handleCreate = async (values: {
+    name: string;
+    expiresAt: string | null;
+  }): Promise<boolean> => {
+    try {
+      const res = await createMutation.mutateAsync(values);
+      setCreateOpened(false);
+      // Move the token into local state, then immediately purge react-query's
+      // own copy of the mutation result so the secret does not linger in the
+      // mutation cache.
+      setCreatedKey(res);
+      createMutation.reset();
+      return true;
+    } catch {
+      notifications.show({
+        message: t("Failed to create API key"),
+        color: "red",
+      });
+      return false;
+    }
+  };
+
+  const handleCloseToken = () => {
+    // Token discarded — the only copy the UI ever held is dropped here.
+    setCreatedKey(null);
+  };
+
+  const openRevokeModal = (key: IApiKey) =>
+    modals.openConfirmModal({
+      title: t("Revoke API key"),
+      centered: true,
+      children: (
+        <Text size="sm">
+          {t(
+            'Are you sure you want to revoke "{{name}}"? Any client using this key will immediately lose access. This cannot be undone.',
+            { name: key.name },
+          )}
+        </Text>
+      ),
+      labels: { confirm: t("Revoke"), cancel: t("Cancel") },
+      confirmProps: { color: "red" },
+      onConfirm: () => revokeMutation.mutate(key.id),
+    });
+
+  const formatDate = (iso: string) =>
+    formatLocalized(new Date(iso), "MMM dd, yyyy", "PP", locale);
+
+  const renderLastUsed = (lastUsedAt: string | null) => {
+    switch (lastUsedBucket(lastUsedAt)) {
+      case "never":
+        return t("Never used");
+      case "recent":
+        return t("Within the last hour");
+      case "stale":
+        // Coarse relative time — last_used_at is throttled to ~1h server-side,
+        // so we don't promise finer precision.
+        return timeAgo(new Date(lastUsedAt as string));
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <Center py="xl">
+        <Loader size="sm" />
+      </Center>
+    );
+  }
+
+  const rows = (keys ?? []).map((key) => {
+    // Mutually exclusive: an already-expired key is labelled "Expired" (a past
+    // expiry) rather than the forward-looking "Expiring soon". isExpiringSoon
+    // also matches past expiries, so gate "soon" on !expired.
+    const expired = isExpired(key.expiresAt);
+    const soon = !expired && isExpiringSoon(key.expiresAt);
+    return (
+      <Table.Tr key={key.id}>
+        <Table.Td>
+          <Text fw={500}>{key.name}</Text>
+        </Table.Td>
+        <Table.Td>{formatDate(key.createdAt)}</Table.Td>
+        <Table.Td>
+          {key.expiresAt ? (
+            <Group gap={6} wrap="nowrap">
+              <Text size="sm">{formatDate(key.expiresAt)}</Text>
+              {expired && (
+                <Tooltip label={t("This key has expired")} withArrow>
+                  <Badge
+                    color="red"
+                    variant="light"
+                    size="sm"
+                    leftSection={<IconAlertTriangle size={12} />}
+                  >
+                    {t("Expired")}
+                  </Badge>
+                </Tooltip>
+              )}
+              {soon && (
+                <Tooltip
+                  label={t("This key expires within 30 days")}
+                  withArrow
+                >
+                  <Badge
+                    color="orange"
+                    variant="light"
+                    size="sm"
+                    leftSection={<IconAlertTriangle size={12} />}
+                  >
+                    {t("Expiring soon")}
+                  </Badge>
+                </Tooltip>
+              )}
+            </Group>
+          ) : (
+            <Text size="sm" c="dimmed">
+              {t("Never")}
+            </Text>
+          )}
+        </Table.Td>
+        <Table.Td>
+          <Text size="sm" c="dimmed">
+            {renderLastUsed(key.lastUsedAt)}
+          </Text>
+        </Table.Td>
+        {isAdmin && (
+          <Table.Td>
+            <Text size="sm">
+              {key.creator?.name ?? key.creator?.email ?? t("Unknown")}
+            </Text>
+          </Table.Td>
+        )}
+        <Table.Td style={{ textAlign: "right" }}>
+          <Tooltip label={t("Revoke")} withArrow>
+            <ActionIcon
+              variant="subtle"
+              color="red"
+              aria-label={t("Revoke {{name}}", { name: key.name })}
+              onClick={() => openRevokeModal(key)}
+            >
+              <IconTrash size={16} />
+            </ActionIcon>
+          </Tooltip>
+        </Table.Td>
+      </Table.Tr>
+    );
+  });
+
+  return (
+    <>
+      <Group justify="space-between" mb="md">
+        <Text size="sm" c="dimmed">
+          {isAdmin
+            ? t("API keys across the workspace.")
+            : t("Your personal API keys.")}
+        </Text>
+        <Button
+          leftSection={<IconKey size={16} />}
+          onClick={() => setCreateOpened(true)}
+        >
+          {t("Create API key")}
+        </Button>
+      </Group>
+
+      {isError ? (
+        <Text c="red" size="sm">
+          {t("Failed to load API keys.")}
+        </Text>
+      ) : rows.length === 0 ? (
+        <Stack align="center" gap="xs" py="xl">
+          <IconKey size={32} opacity={0.4} />
+          <Text c="dimmed">{t("No API keys yet")}</Text>
+          <Button
+            variant="light"
+            leftSection={<IconKey size={16} />}
+            onClick={() => setCreateOpened(true)}
+          >
+            {t("Create API key")}
+          </Button>
+        </Stack>
+      ) : (
+        <Table.ScrollContainer minWidth={600}>
+          <Table verticalSpacing="sm" highlightOnHover>
+            <Table.Thead>
+              <Table.Tr>
+                <Table.Th>{t("Name")}</Table.Th>
+                <Table.Th>{t("Created")}</Table.Th>
+                <Table.Th>{t("Expires")}</Table.Th>
+                <Table.Th>{t("Last used")}</Table.Th>
+                {isAdmin && <Table.Th>{t("Author")}</Table.Th>}
+                <Table.Th />
+              </Table.Tr>
+            </Table.Thead>
+            <Table.Tbody>{rows}</Table.Tbody>
+          </Table>
+        </Table.ScrollContainer>
+      )}
+
+      <CreateApiKeyModal
+        opened={createOpened}
+        onClose={() => setCreateOpened(false)}
+        onSubmit={handleCreate}
+        loading={createMutation.isPending}
+      />
+
+      <ShowTokenModal created={createdKey} onClose={handleCloseToken} />
+    </>
+  );
+}

apps/client/src/features/api-key/components/create-api-key-modal.tsx

@@ -0,0 +1,104 @@
+import { Button, Group, Modal, Select, Stack, TextInput } from "@mantine/core";
+import { useForm } from "@mantine/form";
+import { useTranslation } from "react-i18next";
+import {
+  ApiKeyLifetime,
+  DEFAULT_LIFETIME,
+  lifetimeToExpiresAt,
+} from "@/features/api-key/utils";
+
+interface Props {
+  opened: boolean;
+  onClose: () => void;
+  // Resolves the create request, returning true on success. The parent owns the
+  // mutation (and the token it returns); this modal only collects the name +
+  // lifetime. On failure (false) the form state is kept so the user can retry.
+  onSubmit: (values: {
+    name: string;
+    expiresAt: string | null;
+  }) => Promise<boolean>;
+  loading?: boolean;
+}
+
+interface FormValues {
+  name: string;
+  lifetime: ApiKeyLifetime;
+}
+
+export function CreateApiKeyModal({
+  opened,
+  onClose,
+  onSubmit,
+  loading,
+}: Props) {
+  const { t } = useTranslation();
+
+  const form = useForm<FormValues>({
+    initialValues: {
+      name: "",
+      lifetime: DEFAULT_LIFETIME,
+    },
+    validate: {
+      name: (value) =>
+        value.trim().length === 0 ? t("Name is required") : null,
+    },
+  });
+
+  const lifetimeOptions: { value: ApiKeyLifetime; label: string }[] = [
+    { value: "30d", label: t("30 days") },
+    { value: "90d", label: t("90 days") },
+    { value: "1y", label: t("1 year") },
+    { value: "never", label: t("No expiration") },
+  ];
+
+  const handleSubmit = form.onSubmit(async (values) => {
+    const ok = await onSubmit({
+      name: values.name.trim(),
+      expiresAt: lifetimeToExpiresAt(values.lifetime),
+    });
+    // Reset only after a successful submit so a failed create keeps the form
+    // state (the parent surfaces the error via a notification).
+    if (ok) form.reset();
+  });
+
+  const handleClose = () => {
+    form.reset();
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={handleClose}
+      title={t("Create API key")}
+      centered
+    >
+      <form onSubmit={handleSubmit}>
+        <Stack gap="sm">
+          <TextInput
+            label={t("Name")}
+            placeholder={t("e.g. CI deploy token")}
+            data-autofocus
+            withAsterisk
+            {...form.getInputProps("name")}
+          />
+          <Select
+            label={t("Expiration")}
+            data={lifetimeOptions}
+            allowDeselect={false}
+            checkIconPosition="right"
+            {...form.getInputProps("lifetime")}
+          />
+          <Group justify="flex-end" mt="xs">
+            <Button variant="default" onClick={handleClose} type="button">
+              {t("Cancel")}
+            </Button>
+            <Button type="submit" loading={loading}>
+              {t("Create")}
+            </Button>
+          </Group>
+        </Stack>
+      </form>
+    </Modal>
+  );
+}

apps/client/src/features/api-key/components/show-token-modal.tsx

@@ -0,0 +1,107 @@
+import {
+  Alert,
+  Button,
+  Code,
+  Group,
+  Modal,
+  Stack,
+  Text,
+} from "@mantine/core";
+import { IconAlertTriangle, IconCheck, IconCopy } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { CopyButton } from "@/components/common/copy-button";
+import { formatLocalized, useDateFnsLocale } from "@/lib/date-locale";
+import { ICreateApiKeyResponse } from "@/features/api-key/types/api-key.types";
+
+interface Props {
+  // The freshly-created key incl. its token. Owned by the parent; this modal
+  // only renders it and never copies it into its own persistent state.
+  created: ICreateApiKeyResponse | null;
+  // Closing MUST discard the token in the parent (set the `created` prop back to
+  // null) — the token is shown exactly once.
+  onClose: () => void;
+}
+
+export function ShowTokenModal({ created, onClose }: Props) {
+  const { t } = useTranslation();
+  const locale = useDateFnsLocale();
+
+  const expiresAt = created?.apiKey.expiresAt ?? null;
+
+  return (
+    <Modal
+      opened={created !== null}
+      onClose={onClose}
+      title={t("API key created")}
+      centered
+      // No dismiss-on-outside-click: the token is irretrievable, so closing is a
+      // deliberate act (the user confirms they have saved it).
+      closeOnClickOutside={false}
+    >
+      {created && (
+        <Stack gap="sm">
+          <Alert
+            color="orange"
+            icon={<IconAlertTriangle size={18} />}
+            variant="light"
+          >
+            {t(
+              "Copy your API key now and store it somewhere safe. For security reasons it will not be shown again.",
+            )}
+          </Alert>
+
+          <div>
+            <Text size="sm" c="dimmed" mb={4}>
+              {t("Token")}
+            </Text>
+            <Group gap="xs" wrap="nowrap" align="flex-start">
+              <Code
+                block
+                data-testid="api-key-token"
+                style={{ flex: 1, wordBreak: "break-all" }}
+              >
+                {created.token}
+              </Code>
+              <CopyButton value={created.token}>
+                {({ copied, copy }) => (
+                  <Button
+                    variant="light"
+                    size="xs"
+                    color={copied ? "teal" : "blue"}
+                    leftSection={
+                      copied ? (
+                        <IconCheck size={16} />
+                      ) : (
+                        <IconCopy size={16} />
+                      )
+                    }
+                    onClick={copy}
+                  >
+                    {copied ? t("Copied") : t("Copy")}
+                  </Button>
+                )}
+              </CopyButton>
+            </Group>
+          </div>
+
+          <Text size="sm" c="dimmed">
+            {expiresAt
+              ? t("Expires {{date}}", {
+                  date: formatLocalized(
+                    new Date(expiresAt),
+                    "MMM dd, yyyy",
+                    "PP",
+                    locale,
+                  ),
+                })
+              : t("This key never expires")}
+          </Text>
+
+          <Group justify="flex-end" mt="xs">
+            <Button onClick={onClose}>{t("Done")}</Button>
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}

apps/client/src/features/api-key/queries/api-key-query.ts

@@ -0,0 +1,66 @@
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  UseQueryResult,
+} from "@tanstack/react-query";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
+import {
+  createApiKey,
+  getApiKeys,
+  revokeApiKey,
+} from "@/features/api-key/services/api-key-service";
+import {
+  IApiKey,
+  ICreateApiKey,
+  ICreateApiKeyResponse,
+} from "@/features/api-key/types/api-key.types";
+
+export const API_KEYS_QUERY_KEY = ["api-keys"];
+
+export function useApiKeysQuery(): UseQueryResult<IApiKey[], Error> {
+  return useQuery({
+    queryKey: API_KEYS_QUERY_KEY,
+    queryFn: () => getApiKeys(),
+  });
+}
+
+/**
+ * Create mutation.
+ *
+ * SECURITY: the response contains the token exactly once. This hook deliberately
+ * does NOT stash it anywhere — the caller reads it from `mutateAsync`'s resolved
+ * value, moves it into the show-once modal's local state, then calls
+ * `mutation.reset()` to purge react-query's own copy immediately. `gcTime: 0`
+ * is a second belt so nothing lingers in the mutation cache after the observer
+ * unmounts. The list is invalidated here (the list carries no token).
+ */
+export function useCreateApiKeyMutation() {
+  const queryClient = useQueryClient();
+  return useMutation<ICreateApiKeyResponse, Error, ICreateApiKey>({
+    mutationFn: (data) => createApiKey(data),
+    gcTime: 0,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: API_KEYS_QUERY_KEY });
+    },
+  });
+}
+
+export function useRevokeApiKeyMutation() {
+  const { t } = useTranslation();
+  const queryClient = useQueryClient();
+  return useMutation<void, Error, string>({
+    mutationFn: (id) => revokeApiKey(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: API_KEYS_QUERY_KEY });
+      notifications.show({ message: t("API key revoked") });
+    },
+    onError: () => {
+      notifications.show({
+        message: t("Failed to revoke API key"),
+        color: "red",
+      });
+    },
+  });
+}

apps/client/src/features/api-key/services/api-key-service.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock the api-client (axios instance). vi.mock replaces the whole module, so
+// the real response interceptor — which returns `response.data`, i.e. the
+// server envelope { data, success, status } — is bypassed. Our mocked post/get
+// therefore resolve to that post-interceptor envelope shape directly, and the
+// service under test reads `.data` off it to unwrap the inner payload. This is
+// the one bug-prone line the component tests (which fully mock the service)
+// never exercise.
+const { post, get } = vi.hoisted(() => ({ post: vi.fn(), get: vi.fn() }));
+vi.mock("@/lib/api-client", () => ({
+  default: { post, get },
+}));
+
+import {
+  createApiKey,
+  getApiKeys,
+} from "@/features/api-key/services/api-key-service";
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("api-key-service response-contract unwrap", () => {
+  it("createApiKey unwraps the envelope to { token, apiKey }", async () => {
+    const payload = {
+      token: "gm_secret-abc",
+      apiKey: {
+        id: "key-1",
+        name: "CI token",
+        expiresAt: "2027-07-11T12:00:00.000Z",
+        createdAt: "2026-07-11T12:00:00.000Z",
+      },
+    };
+    // The server envelope as the interceptor hands it to the service.
+    post.mockResolvedValue({ data: payload, success: true, status: 200 });
+
+    const result = await createApiKey({
+      name: "CI token",
+      expiresAt: "2027-07-11T12:00:00.000Z",
+    });
+
+    // The inner payload only — not the { data, success, status } wrapper.
+    expect(result).toEqual(payload);
+    expect(result.token).toBe("gm_secret-abc");
+    expect(result.apiKey).toEqual(payload.apiKey);
+    expect(post).toHaveBeenCalledWith("/api-keys/create", {
+      name: "CI token",
+      expiresAt: "2027-07-11T12:00:00.000Z",
+    });
+  });
+
+  it("getApiKeys unwraps the envelope to the array of rows", async () => {
+    const rows = [
+      {
+        id: "key-1",
+        name: "CI token",
+        expiresAt: null,
+        lastUsedAt: null,
+        createdAt: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        id: "key-2",
+        name: "Deploy token",
+        expiresAt: "2027-01-01T00:00:00.000Z",
+        lastUsedAt: null,
+        createdAt: "2026-02-01T00:00:00.000Z",
+      },
+    ];
+    post.mockResolvedValue({ data: rows, success: true, status: 200 });
+
+    const result = await getApiKeys();
+
+    expect(result).toEqual(rows);
+    expect(result).toHaveLength(2);
+    expect(post).toHaveBeenCalledWith("/api-keys/list");
+  });
+});

apps/client/src/features/api-key/services/api-key-service.ts

@@ -0,0 +1,30 @@
+import api from "@/lib/api-client";
+import {
+  IApiKey,
+  ICreateApiKey,
+  ICreateApiKeyResponse,
+} from "@/features/api-key/types/api-key.types";
+
+// Mint a new key. The response carries the token ONCE — the caller must move it
+// straight into the show-once modal's local state and never cache it. See
+// queries/api-key-query.ts (gcTime: 0 + query invalidation) and
+// components/api-keys-manager.tsx `handleCreate` (createMutation.reset() right
+// after reading the token) for the reset()-after-read pattern.
+export async function createApiKey(
+  data: ICreateApiKey,
+): Promise<ICreateApiKeyResponse> {
+  const res = await api.post<ICreateApiKeyResponse>("/api-keys/create", data);
+  return res.data as ICreateApiKeyResponse;
+}
+
+// List the caller's keys (or, for an admin, every key in the workspace with
+// creator attribution). Never returns token material.
+export async function getApiKeys(): Promise<IApiKey[]> {
+  const res = await api.post<IApiKey[]>("/api-keys/list");
+  return res.data as IApiKey[];
+}
+
+// Revocation is server-side immediate; the caller drops the row on success.
+export async function revokeApiKey(id: string): Promise<void> {
+  await api.post("/api-keys/revoke", { id });
+}

apps/client/src/features/api-key/types/api-key.types.ts

@@ -0,0 +1,48 @@
+// Compact creator attribution embedded in the admin (workspace-wide) list. A
+// normal member's list only ever contains their own keys, so the field is
+// present but redundant; the author column is only rendered for admins.
+export interface IApiKeyCreator {
+  id: string;
+  name: string;
+  email: string;
+  avatarUrl: string | null;
+}
+
+// A single api-key row as returned by `POST /api/api-keys/list`. Note: the list
+// NEVER carries token material — only metadata.
+export interface IApiKey {
+  id: string;
+  name: string;
+  // ISO string, or null for an unlimited ("never expires") key.
+  expiresAt: string | null;
+  // ISO string, or null if the key was never used. Throttled to ~1h server-side
+  // (#501), so the UI must not promise sub-hour precision.
+  lastUsedAt: string | null;
+  createdAt: string;
+  creator?: IApiKeyCreator | null;
+}
+
+// Payload for `POST /api/api-keys/create`. `expiresAt`: an ISO date string for a
+// bounded lifetime, or null for an unlimited key. (undefined would let the
+// server apply its 1-year default, but the form always sends an explicit value.)
+export interface ICreateApiKey {
+  name: string;
+  expiresAt: string | null;
+}
+
+// The metadata half of the create response. The token itself is carried
+// separately (see ICreateApiKeyResponse) and is shown exactly once.
+export interface ICreatedApiKey {
+  id: string;
+  name: string;
+  expiresAt: string | null;
+  createdAt: string;
+}
+
+// Response of `POST /api/api-keys/create`. `token` is the ONLY time the secret
+// is ever returned — it must live only in the show-once modal's local state and
+// must never be cached, persisted or logged.
+export interface ICreateApiKeyResponse {
+  token: string;
+  apiKey: ICreatedApiKey;
+}

apps/client/src/features/api-key/utils.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import {
+  DEFAULT_LIFETIME,
+  EXPIRY_WARNING_DAYS,
+  isExpired,
+  isExpiringSoon,
+  lastUsedBucket,
+  lifetimeToExpiresAt,
+} from "./utils";
+
+const NOW = new Date("2026-07-11T12:00:00.000Z");
+const daysFromNow = (n: number) =>
+  new Date(NOW.getTime() + n * 24 * 60 * 60 * 1000).toISOString();
+
+describe("lifetimeToExpiresAt", () => {
+  it("default lifetime is 1 year (acceptance #7)", () => {
+    expect(DEFAULT_LIFETIME).toBe("1y");
+    const iso = lifetimeToExpiresAt("1y", NOW);
+    expect(iso).toBe("2027-07-11T12:00:00.000Z");
+  });
+
+  it('"never" sends null (acceptance #7)', () => {
+    expect(lifetimeToExpiresAt("never", NOW)).toBeNull();
+  });
+
+  it("30d / 90d map to the exact future instant", () => {
+    expect(lifetimeToExpiresAt("30d", NOW)).toBe(daysFromNow(30));
+    expect(lifetimeToExpiresAt("90d", NOW)).toBe(daysFromNow(90));
+  });
+});
+
+describe("isExpiringSoon (acceptance #3 highlight)", () => {
+  it("an unlimited key is never 'soon'", () => {
+    expect(isExpiringSoon(null, NOW)).toBe(false);
+  });
+
+  it("highlights a key expiring within the 30-day window", () => {
+    expect(isExpiringSoon(daysFromNow(EXPIRY_WARNING_DAYS - 1), NOW)).toBe(true);
+    expect(isExpiringSoon(daysFromNow(10), NOW)).toBe(true);
+  });
+
+  it("does not highlight a key well outside the window", () => {
+    expect(isExpiringSoon(daysFromNow(EXPIRY_WARNING_DAYS + 1), NOW)).toBe(
+      false,
+    );
+    expect(isExpiringSoon(daysFromNow(200), NOW)).toBe(false);
+  });
+
+  it("an already-expired key is highlighted", () => {
+    expect(isExpiringSoon(daysFromNow(-3), NOW)).toBe(true);
+  });
+});
+
+describe("isExpired (past vs future expiry)", () => {
+  it("an unlimited key is never expired", () => {
+    expect(isExpired(null, NOW)).toBe(false);
+  });
+
+  it("a past expiry is expired", () => {
+    expect(isExpired(daysFromNow(-3), NOW)).toBe(true);
+    expect(isExpired(daysFromNow(-1), NOW)).toBe(true);
+  });
+
+  it("a future expiry is not expired (even within the warning window)", () => {
+    expect(isExpired(daysFromNow(1), NOW)).toBe(false);
+    expect(isExpired(daysFromNow(EXPIRY_WARNING_DAYS - 1), NOW)).toBe(false);
+    expect(isExpired(daysFromNow(200), NOW)).toBe(false);
+  });
+
+  it("an expiry exactly at 'now' counts as expired (boundary is inclusive)", () => {
+    expect(isExpired(NOW.toISOString(), NOW)).toBe(true);
+  });
+
+  it("is mutually distinguishable from isExpiringSoon: expired vs soon-but-future", () => {
+    // A key 3 days in the past: expired, and (by design) also matches
+    // isExpiringSoon — the UI resolves this by checking isExpired first.
+    expect(isExpired(daysFromNow(-3), NOW)).toBe(true);
+    // A key 10 days in the future: NOT expired, but expiring soon.
+    expect(isExpired(daysFromNow(10), NOW)).toBe(false);
+    expect(isExpiringSoon(daysFromNow(10), NOW)).toBe(true);
+  });
+});
+
+describe("lastUsedBucket (within-the-last-hour semantics)", () => {
+  const minutesAgo = (n: number) =>
+    new Date(NOW.getTime() - n * 60 * 1000).toISOString();
+
+  it("null last-used is 'never'", () => {
+    expect(lastUsedBucket(null, NOW)).toBe("never");
+  });
+
+  it("under an hour is 'recent' (no sub-hour precision promised)", () => {
+    expect(lastUsedBucket(minutesAgo(5), NOW)).toBe("recent");
+    expect(lastUsedBucket(minutesAgo(59), NOW)).toBe("recent");
+  });
+
+  it("over an hour is 'stale'", () => {
+    expect(lastUsedBucket(minutesAgo(90), NOW)).toBe("stale");
+  });
+});

apps/client/src/features/api-key/utils.ts

@@ -0,0 +1,76 @@
+import { addDays, addYears, differenceInMinutes } from "date-fns";
+
+// The single early-warning window (#501/#506): keys whose expiry is closer than
+// this are visually highlighted in the list. Also used to classify a key as
+// already-expired (a negative "days until" is < 30 too).
+export const EXPIRY_WARNING_DAYS = 30;
+
+// last_used_at is throttled to ~1h server-side, so anything under an hour is
+// shown as the coarse "within the last hour" rather than a false-precise
+// "5 minutes ago".
+export const LAST_USED_THROTTLE_MINUTES = 60;
+
+export type ApiKeyLifetime = "30d" | "90d" | "1y" | "never";
+
+export const DEFAULT_LIFETIME: ApiKeyLifetime = "1y";
+
+// Maps a lifetime choice to the `expiresAt` payload sent to the server: an ISO
+// string for a bounded lifetime, or null for an explicit unlimited key.
+export function lifetimeToExpiresAt(
+  lifetime: ApiKeyLifetime,
+  now: Date = new Date(),
+): string | null {
+  switch (lifetime) {
+    case "30d":
+      return addDays(now, 30).toISOString();
+    case "90d":
+      return addDays(now, 90).toISOString();
+    case "1y":
+      return addYears(now, 1).toISOString();
+    case "never":
+      return null;
+  }
+}
+
+// True when a bounded key's expiry is already in the past (or exactly now). An
+// unlimited key (null) is never expired. This is distinct from "expiring soon":
+// the two states are mutually exclusive at the call site (see api-keys-manager),
+// so an already-expired key is labelled "Expired", not "Expiring soon".
+export function isExpired(
+  expiresAt: string | null,
+  now: Date = new Date(),
+): boolean {
+  if (!expiresAt) return false;
+  const expiry = new Date(expiresAt).getTime();
+  if (Number.isNaN(expiry)) return false;
+  return expiry <= now.getTime();
+}
+
+// True when a bounded key expires within the warning window (or is already
+// expired). An unlimited key (null) is never "expiring soon". Callers that need
+// to distinguish an already-past expiry should check isExpired() first, as this
+// predicate deliberately also covers the already-expired case.
+export function isExpiringSoon(
+  expiresAt: string | null,
+  now: Date = new Date(),
+): boolean {
+  if (!expiresAt) return false;
+  const expiry = new Date(expiresAt).getTime();
+  if (Number.isNaN(expiry)) return false;
+  const msLeft = expiry - now.getTime();
+  return msLeft < EXPIRY_WARNING_DAYS * 24 * 60 * 60 * 1000;
+}
+
+// Classifies last-used recency so the caller can pick the honest label without
+// promising sub-hour precision. Returns "never", "recent" (< 1h) or "stale".
+export function lastUsedBucket(
+  lastUsedAt: string | null,
+  now: Date = new Date(),
+): "never" | "recent" | "stale" {
+  if (!lastUsedAt) return "never";
+  const used = new Date(lastUsedAt);
+  if (Number.isNaN(used.getTime())) return "never";
+  return differenceInMinutes(now, used) < LAST_USED_THROTTLE_MINUTES
+    ? "recent"
+    : "stale";
+}

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

@@ -27,11 +27,15 @@ vi.mock("@/features/space/queries/space-query.ts", () => ({
 import {
   buildChildrenByParent,
   CommentEditorWithActions,
+  sortResolvedByResolvedAt,
 } from "./comment-list-with-tabs";
 
 const c = (id: string, parentCommentId: string | null = null): IComment =>
   ({ id, parentCommentId }) as IComment;
 
+const resolvedAtComment = (id: string, resolvedAt: unknown): IComment =>
+  ({ id, resolvedAt }) as unknown as IComment;
+
 describe("buildChildrenByParent (childrenByParent grouping)", () => {
   it("returns an empty map for undefined or empty input", () => {
     expect(buildChildrenByParent(undefined).size).toBe(0);
@@ -71,6 +75,48 @@ describe("buildChildrenByParent (childrenByParent grouping)", () => {
   });
 });
 
+describe("sortResolvedByResolvedAt (Resolved tab order, #542)", () => {
+  it("orders by resolvedAt DESC — newest resolve first — with ISO-STRING values", () => {
+    // At runtime resolvedAt is an ISO string (axios JSON / WS subscription), so
+    // the sort must coerce with new Date(...) before .getTime().
+    const older = resolvedAtComment("older", "2026-07-10T10:00:00.000Z");
+    const newest = resolvedAtComment("newest", "2026-07-12T10:00:00.000Z");
+    const middle = resolvedAtComment("middle", "2026-07-11T10:00:00.000Z");
+
+    const out = sortResolvedByResolvedAt([older, newest, middle]);
+    expect(out.map((x) => x.id)).toEqual(["newest", "middle", "older"]);
+  });
+
+  it("also handles Date instances (optimistic onMutate window)", () => {
+    const older = resolvedAtComment("older", new Date("2026-01-01T00:00:00Z"));
+    const newer = resolvedAtComment("newer", new Date("2026-06-01T00:00:00Z"));
+    expect(sortResolvedByResolvedAt([older, newer]).map((x) => x.id)).toEqual([
+      "newer",
+      "older",
+    ]);
+  });
+
+  it("does not mutate the input array", () => {
+    const a = resolvedAtComment("a", "2026-01-01T00:00:00.000Z");
+    const b = resolvedAtComment("b", "2026-02-01T00:00:00.000Z");
+    const input = [a, b];
+    sortResolvedByResolvedAt(input);
+    expect(input.map((x) => x.id)).toEqual(["a", "b"]);
+  });
+
+  it("keeps stable order for equal resolvedAt timestamps", () => {
+    const ts = "2026-03-03T03:03:03.000Z";
+    const x = resolvedAtComment("x", ts);
+    const y = resolvedAtComment("y", ts);
+    const z = resolvedAtComment("z", ts);
+    expect(sortResolvedByResolvedAt([x, y, z]).map((c) => c.id)).toEqual([
+      "x",
+      "y",
+      "z",
+    ]);
+  });
+});
+
 function renderReplyEditor() {
   return render(
     <MantineProvider>

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

@@ -53,6 +53,22 @@ export function buildChildrenByParent(
   return m;
 }
 
+// Sort the Resolved tab by resolve time, newest first, on a COPY (never mutate
+// the react-query cache array). `resolvedAt` is typed `Date` but at runtime it
+// is an ISO STRING (from the axios-JSON onSuccess and the WS subscription) — a
+// real Date only during the optimistic onMutate window — so it MUST be coerced
+// with `new Date(...)` before `.getTime()`, or a raw `.getTime()` on the string
+// throws / yields NaN. ES2019's stable sort preserves order for equal
+// timestamps. Callers pass a list already filtered to a truthy `resolvedAt`, so
+// the non-null assertion is safe.
+// Exported for unit testing.
+export function sortResolvedByResolvedAt(resolved: IComment[]): IComment[] {
+  return [...resolved].sort(
+    (a, b) =>
+      new Date(b.resolvedAt!).getTime() - new Date(a.resolvedAt!).getTime(),
+  );
+}
+
 function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
@@ -91,7 +107,10 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
       (comment: IComment) => comment.resolvedAt,
     );
 
-    return { activeComments: active, resolvedComments: resolved };
+    return {
+      activeComments: active,
+      resolvedComments: sortResolvedByResolvedAt(resolved),
+    };
   }, [comments]);
 
   // Index replies by their parent once, instead of an O(n^2) filter per thread.

apps/client/src/features/comment/queries/comment-query.resolve-undo.test.tsx

@@ -0,0 +1,353 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import {
+  QueryClient,
+  QueryClientProvider,
+  InfiniteData,
+} from "@tanstack/react-query";
+
+/**
+ * Coverage for the resolve/reopen mutation (#542): the Undo-in-toast reopen and
+ * its double-click guard, the terminal 404 branch (drop from cache + clear the
+ * inline mark, no rollback), and the directional error copy.
+ */
+
+// A fake TipTap editor injected via the mocked pageEditorAtom, so we can assert
+// the mutation clears the inline comment mark (unsetComment / setCommentResolved).
+const editorMock = vi.hoisted(() => ({
+  current: {
+    isDestroyed: false,
+    commands: { unsetComment: vi.fn(), setCommentResolved: vi.fn() },
+  } as {
+    isDestroyed: boolean;
+    commands: {
+      unsetComment: (id: string) => void;
+      setCommentResolved: (id: string, v: boolean) => void;
+    };
+  } | null,
+}));
+
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: vi.fn(), hide: vi.fn() },
+}));
+
+vi.mock("jotai", () => ({
+  atom: (v: unknown) => v,
+  useAtomValue: () => editorMock.current,
+}));
+
+vi.mock("@/features/comment/services/comment-service", () => ({
+  applySuggestion: vi.fn(),
+  dismissSuggestion: vi.fn(),
+  createComment: vi.fn(),
+  updateComment: vi.fn(),
+  deleteComment: vi.fn(),
+  resolveComment: vi.fn(),
+  getPageComments: vi.fn(),
+}));
+
+import { notifications } from "@mantine/notifications";
+import { resolveComment } from "@/features/comment/services/comment-service";
+import {
+  useResolveCommentMutation,
+  RESOLVE_UNDO_AUTOCLOSE_MS,
+  RQ_KEY,
+} from "@/features/comment/queries/comment-query";
+import { IComment } from "@/features/comment/types/comment.types";
+
+const PAGE_ID = "page-1";
+
+function seededClient(comment: IComment) {
+  const queryClient = new QueryClient({
+    defaultOptions: { mutations: { retry: false } },
+  });
+  const seed: InfiniteData<any> = {
+    pageParams: [undefined],
+    pages: [
+      { items: [comment], meta: { hasNextPage: false, nextCursor: null } },
+    ],
+  };
+  queryClient.setQueryData(RQ_KEY(PAGE_ID), seed);
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+  return { queryClient, wrapper };
+}
+
+function items(queryClient: QueryClient): IComment[] {
+  const cache = queryClient.getQueryData(RQ_KEY(PAGE_ID)) as
+    | InfiniteData<any>
+    | undefined;
+  return cache?.pages.flatMap((p) => p.items) ?? [];
+}
+
+const comment = (over?: Partial<IComment>): IComment =>
+  ({
+    id: "c-1",
+    pageId: PAGE_ID,
+    content: "{}",
+    creatorId: "u-1",
+    workspaceId: "ws-1",
+    createdAt: new Date(),
+    resolvedAt: null,
+    ...over,
+  }) as IComment;
+
+// Pull the inline Undo button's onClick out of the success toast's message tree.
+function undoOnClickFromToast(): () => void {
+  const call = vi
+    .mocked(notifications.show)
+    .mock.calls.map((c) => c[0])
+    .find((arg: any) => arg?.autoClose === RESOLVE_UNDO_AUTOCLOSE_MS);
+  expect(call).toBeTruthy();
+  const message: any = (call as any).message;
+  // message = Group( Text, Button ); grab the Button element's onClick.
+  const children = message.props.children as any[];
+  const button = children[1];
+  return button.props.onClick;
+}
+
+describe("useResolveCommentMutation — Undo toast (#542)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    editorMock.current = {
+      isDestroyed: false,
+      commands: { unsetComment: vi.fn(), setCommentResolved: vi.fn() },
+    };
+  });
+
+  it("resolve shows an Undo toast with autoClose=10000ms; reopen shows NO Undo", async () => {
+    vi.mocked(resolveComment).mockImplementation(async (data) =>
+      comment({
+        resolvedAt: data.resolved ? (new Date() as any) : null,
+      }),
+    );
+    const { wrapper } = seededClient(comment());
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync({
+      commentId: "c-1",
+      pageId: PAGE_ID,
+      resolved: true,
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    const resolveToast = vi
+      .mocked(notifications.show)
+      .mock.calls.map((c) => c[0])
+      .find((a: any) => a?.autoClose === RESOLVE_UNDO_AUTOCLOSE_MS);
+    expect(resolveToast).toBeTruthy();
+    expect((resolveToast as any).id).toBe("resolve-undo-c-1");
+    expect((resolveToast as any).autoClose).toBe(10000);
+
+    // Now a reopen → plain toast, no autoClose/Undo, no id.
+    vi.clearAllMocks();
+    await result.current.mutateAsync({
+      commentId: "c-1",
+      pageId: PAGE_ID,
+      resolved: false,
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    const calls = vi.mocked(notifications.show).mock.calls.map((c) => c[0]);
+    expect(
+      calls.some((a: any) => a?.autoClose === RESOLVE_UNDO_AUTOCLOSE_MS),
+    ).toBe(false);
+    expect(calls).toContainEqual({ message: "Comment re-opened successfully" });
+  });
+
+  it("double/fast Undo click fires reopen EXACTLY once (guard)", async () => {
+    vi.mocked(resolveComment).mockImplementation(async (data) =>
+      comment({ resolvedAt: data.resolved ? (new Date() as any) : null }),
+    );
+    const { wrapper } = seededClient(comment());
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync({
+      commentId: "c-1",
+      pageId: PAGE_ID,
+      resolved: true,
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    const onClick = undoOnClickFromToast();
+    // Fire twice synchronously (notifications.hide is not synchronous).
+    onClick();
+    onClick();
+
+    await waitFor(() => {
+      const reopenCalls = vi
+        .mocked(resolveComment)
+        .mock.calls.filter(([d]) => d.resolved === false);
+      expect(reopenCalls).toHaveLength(1);
+    });
+    // The mark was cleared once via setCommentResolved(id, false).
+    expect(editorMock.current!.commands.setCommentResolved).toHaveBeenCalledWith(
+      "c-1",
+      false,
+    );
+    // The toast was hidden.
+    expect(notifications.hide).toHaveBeenCalledWith("resolve-undo-c-1");
+  });
+
+  it("404 → drops the comment from cache, clears the inline mark, no rollback, no Undo", async () => {
+    vi.mocked(resolveComment).mockRejectedValue({ response: { status: 404 } });
+    const { queryClient, wrapper } = seededClient(comment());
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current
+      .mutateAsync({ commentId: "c-1", pageId: PAGE_ID, resolved: true })
+      .catch(() => undefined);
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    // Removed from cache (NOT rolled back to a phantom).
+    expect(items(queryClient)).toHaveLength(0);
+    // Inline mark cleared via unsetComment (mandatory — no panel row left to do it).
+    expect(editorMock.current!.commands.unsetComment).toHaveBeenCalledWith(
+      "c-1",
+    );
+    // Neutral message, red, and crucially NOT the success copy and NO Undo toast.
+    expect(notifications.show).toHaveBeenCalledWith({
+      message: "Comment no longer exists",
+      color: "red",
+    });
+    const calls = vi.mocked(notifications.show).mock.calls.map((c) => c[0]);
+    expect(
+      calls.some((a: any) => a?.autoClose === RESOLVE_UNDO_AUTOCLOSE_MS),
+    ).toBe(false);
+  });
+
+  it("404 does not crash when the editor is gone (read-only / panel closed)", async () => {
+    editorMock.current = null;
+    vi.mocked(resolveComment).mockRejectedValue({ response: { status: 404 } });
+    const { queryClient, wrapper } = seededClient(comment());
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current
+      .mutateAsync({ commentId: "c-1", pageId: PAGE_ID, resolved: true })
+      .catch(() => undefined);
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    expect(items(queryClient)).toHaveLength(0);
+    expect(notifications.show).toHaveBeenCalledWith({
+      message: "Comment no longer exists",
+      color: "red",
+    });
+  });
+
+  it("non-404 error on REOPEN shows 'Failed to re-open comment' and rolls back", async () => {
+    vi.mocked(resolveComment).mockRejectedValue({ response: { status: 500 } });
+    // Seed a RESOLVED comment (the reopen target).
+    const resolved = comment({ resolvedAt: new Date() as any });
+    const { queryClient, wrapper } = seededClient(resolved);
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current
+      .mutateAsync({ commentId: "c-1", pageId: PAGE_ID, resolved: false })
+      .catch(() => undefined);
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    expect(notifications.show).toHaveBeenCalledWith({
+      message: "Failed to re-open comment",
+      color: "red",
+    });
+    expect(notifications.show).not.toHaveBeenCalledWith(
+      expect.objectContaining({ message: "Failed to resolve comment" }),
+    );
+    // Rolled back: the comment is still present and still resolved.
+    expect(items(queryClient)).toHaveLength(1);
+    expect(items(queryClient)[0].resolvedAt).toBeTruthy();
+  });
+
+  it("reopen via Undo FAILS (non-404) → inline mark is NOT left cleared (doc↔panel stay consistent)", async () => {
+    // First resolve succeeds → produces the Undo toast (no mark change on resolve).
+    vi.mocked(resolveComment).mockResolvedValueOnce(
+      comment({ resolvedAt: new Date() as any }),
+    );
+    const { queryClient, wrapper } = seededClient(comment());
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync({
+      commentId: "c-1",
+      pageId: PAGE_ID,
+      resolved: true,
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    // Now the reopen fired by Undo fails with a 500.
+    vi.mocked(resolveComment).mockRejectedValue({ response: { status: 500 } });
+    const onClick = undoOnClickFromToast();
+    onClick();
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    // Core F1 guarantee: the mark-clear now lives in the reopen onSuccess, so a
+    // FAILED reopen must never flip the inline mark to unresolved — otherwise the
+    // doc would show an active highlight the panel still treats as resolved and
+    // the collab mark would diverge with nothing committed on the server.
+    expect(
+      editorMock.current!.commands.setCommentResolved,
+    ).not.toHaveBeenCalledWith("c-1", false);
+    // Cache rolled back: the comment stays resolved and present.
+    expect(items(queryClient)).toHaveLength(1);
+    expect(items(queryClient)[0].resolvedAt).toBeTruthy();
+  });
+
+  it("reopen success with a null editorRef degrades gracefully (no throw, no-op)", async () => {
+    // Read-only view / panel closed: pageEditorAtom is null on the success path.
+    editorMock.current = null;
+    vi.mocked(resolveComment).mockResolvedValue(comment({ resolvedAt: null }));
+    const resolved = comment({ resolvedAt: new Date() as any });
+    const { queryClient, wrapper } = seededClient(resolved);
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current.mutateAsync({
+      commentId: "c-1",
+      pageId: PAGE_ID,
+      resolved: false,
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+
+    // No crash from the reopen mark-clear; the plain reopen toast is still shown.
+    expect(notifications.show).toHaveBeenCalledWith({
+      message: "Comment re-opened successfully",
+    });
+    // Cache updated to reopened (resolvedAt cleared by the server payload).
+    expect(items(queryClient)).toHaveLength(1);
+    expect(items(queryClient)[0].resolvedAt).toBeFalsy();
+  });
+
+  it("non-404 error on RESOLVE shows 'Failed to resolve comment' and rolls back", async () => {
+    vi.mocked(resolveComment).mockRejectedValue({ response: { status: 500 } });
+    const { queryClient, wrapper } = seededClient(comment());
+    const { result } = renderHook(() => useResolveCommentMutation(), {
+      wrapper,
+    });
+
+    await result.current
+      .mutateAsync({ commentId: "c-1", pageId: PAGE_ID, resolved: true })
+      .catch(() => undefined);
+    await waitFor(() => expect(result.current.isError).toBe(true));
+
+    expect(notifications.show).toHaveBeenCalledWith({
+      message: "Failed to resolve comment",
+      color: "red",
+    });
+    // Rolled back to open (previousCache), still present.
+    expect(items(queryClient)).toHaveLength(1);
+    expect(items(queryClient)[0].resolvedAt).toBeFalsy();
+  });
+});

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

@@ -20,12 +20,19 @@ import {
   ISuggestionOutcome,
 } from "@/features/comment/types/comment.types";
 import { notifications } from "@mantine/notifications";
+import { Button, Group, Text } from "@mantine/core";
 import { IPagination } from "@/lib/types.ts";
 import { useTranslation } from "react-i18next";
-import { useEffect, useMemo } from "react";
+import React, { useEffect, useMemo, useRef } from "react";
+import { useAtomValue } from "jotai";
+import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms";
 
 export const RQ_KEY = (pageId: string) => ["comments", pageId];
 
+// How long the resolve success toast (with its inline Undo) stays up before it
+// auto-closes. Policy constant — no env override.
+export const RESOLVE_UNDO_AUTOCLOSE_MS = 10000;
+
 export function useCommentsQuery(params: ICommentParams) {
   const query = useInfiniteQuery({
     queryKey: RQ_KEY(params.pageId),
@@ -376,7 +383,25 @@ export function useResolveCommentMutation() {
   const queryClient = useQueryClient();
   const { t } = useTranslation();
 
-  return useMutation({
+  // Keep the live editor in a ref: the toast's Undo (and the 404 branch) must
+  // clear the inline comment mark AFTER the originating CommentListItem has
+  // unmounted (resolving pulls the comment out of the Open list, so its item is
+  // already gone by the time the 10s toast is clicked). In read-only view
+  // pageEditorAtom is null and the mark converges via the server's
+  // COMMENT_MARK_UPDATE job instead.
+  const editor = useAtomValue(pageEditorAtom);
+  const editorRef = useRef(editor);
+  editorRef.current = editor;
+
+  // Self-reference the mutation so the toast's Undo can re-invoke it (reopen)
+  // long after the triggering component unmounted. Declared BEFORE useMutation
+  // and assigned AFTER; the onClick reads mutationRef.current at CALL time, not
+  // definition time, so there is no initialization cycle.
+  const mutationRef = useRef<{
+    mutate: (vars: IResolveComment) => void;
+  } | null>(null);
+
+  const mutation = useMutation({
     mutationFn: (data: IResolveComment) => resolveComment(data),
     onMutate: async (variables) => {
       await queryClient.cancelQueries({ queryKey: RQ_KEY(variables.pageId) });
@@ -401,7 +426,39 @@ export function useResolveCommentMutation() {
 
       return { previousCache };
     },
-    onError: (_err, variables, context) => {
+    onError: (err: any, variables, context) => {
+      // Terminal 404: the comment was really deleted (missing comment or deleted
+      // page — access denial is 403, resolve is idempotent so no 400). Do NOT
+      // roll back (that would resurrect a phantom row in Resolved); instead drop
+      // it from the cache and clear its now-orphaned inline mark. Mirrors
+      // handleDeleteComment and the dismiss-mutation 404 branch.
+      if (err?.response?.status === 404) {
+        const cache = queryClient.getQueryData(RQ_KEY(variables.pageId)) as
+          | InfiniteData<IPagination<IComment>>
+          | undefined;
+        if (cache) {
+          queryClient.setQueryData(
+            RQ_KEY(variables.pageId),
+            removeCommentFromCache(cache, variables.commentId),
+          );
+        }
+        const ed = editorRef.current;
+        if (ed && !ed.isDestroyed) {
+          try {
+            ed.commands.unsetComment(variables.commentId);
+          } catch {
+            /* editor gone / mark already removed */
+          }
+        }
+        notifications.show({
+          message: t("Comment no longer exists"),
+          color: "red",
+        });
+        return;
+      }
+
+      // Generic failure: roll back the optimistic update and show a DIRECTIONAL
+      // error (resolve vs. reopen), not always "resolve".
       if (context?.previousCache) {
         queryClient.setQueryData(
           RQ_KEY(variables.pageId),
@@ -409,7 +466,9 @@ export function useResolveCommentMutation() {
         );
       }
       notifications.show({
-        message: t("Failed to resolve comment"),
+        message: variables.resolved
+          ? t("Failed to resolve comment")
+          : t("Failed to re-open comment"),
         color: "red",
       });
     },
@@ -430,11 +489,72 @@ export function useResolveCommentMutation() {
         );
       }
 
+      // Reopen keeps the plain toast without an Undo.
+      if (!variables.resolved) {
+        // Clear the inline mark ONLY after the server confirms the reopen, so a
+        // failed reopen never leaves an active highlight the panel still treats
+        // as resolved. Mirrors the 404 branch's editor-liveness guard/try-catch.
+        // The button-triggered reopen already set the mark, so this is an
+        // idempotent no-op there.
+        const ed = editorRef.current;
+        if (ed && !ed.isDestroyed) {
+          try {
+            ed.commands.setCommentResolved(variables.commentId, false);
+          } catch {
+            /* editor gone — server COMMENT_MARK_UPDATE converges it */
+          }
+        }
+        notifications.show({ message: t("Comment re-opened successfully") });
+        return;
+      }
+
+      // Resolve: attach an inline Undo (reopen) to the success toast. Built with
+      // React.createElement because this is a .ts module (no JSX).
+      const { commentId, pageId } = variables;
+      const notificationId = `resolve-undo-${commentId}`;
+      // Double-click guard: notifications.hide is NOT synchronous, so the button
+      // stays clickable for a frame or two — without this a fast double-click
+      // would fire reopen twice.
+      let done = false;
       notifications.show({
-        message: variables.resolved
-          ? t("Comment resolved successfully")
-          : t("Comment re-opened successfully"),
+        id: notificationId,
+        autoClose: RESOLVE_UNDO_AUTOCLOSE_MS,
+        message: React.createElement(
+          Group,
+          { justify: "space-between", wrap: "nowrap", gap: "md" },
+          React.createElement(
+            Text,
+            { size: "sm" },
+            t("Comment resolved successfully"),
+          ),
+          React.createElement(
+            Button,
+            {
+              variant: "subtle",
+              size: "compact-sm",
+              onClick: () => {
+                if (done) return;
+                done = true;
+                // Reopen via the SAME mutation (read at click time — the
+                // originating item is already unmounted).
+                mutationRef.current?.mutate({
+                  commentId,
+                  pageId,
+                  resolved: false,
+                });
+                // The inline mark is cleared in the reopen mutation's onSuccess
+                // (bound to server confirmation), NOT here — clearing it eagerly
+                // would desync the doc from the panel if reopen then fails.
+                notifications.hide(notificationId);
+              },
+            },
+            t("Undo"),
+          ),
+        ),
       });
     },
   });
+
+  mutationRef.current = mutation;
+  return mutation;
 }

apps/client/src/features/page-history/work-time/format-work-time.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import {
+  formatHeadline,
+  formatDayTotal,
+  formatGapMinutes,
+} from "./format-work-time";
+
+const MIN = 60 * 1000;
+// Fake translator: renders the key with {{tokens}} substituted, so the tests
+// assert the rounding + branch selection without depending on the i18n catalogue.
+const t = (key: string, opts?: Record<string, unknown>) =>
+  key.replace(/\{\{(\w+)\}\}/g, (_, k) => String(opts?.[k] ?? ""));
+
+describe("formatHeadline", () => {
+  it("prefixes ≈ and rounds to a 5-minute step", () => {
+    expect(formatHeadline(4 * 60 * MIN + 27 * MIN, t)).toBe("≈ 4h 25m");
+    expect(formatHeadline(90 * MIN, t)).toBe("≈ 1h 30m");
+  });
+
+  it("shows hours only / minutes only cleanly", () => {
+    expect(formatHeadline(120 * MIN, t)).toBe("≈ 2h");
+    expect(formatHeadline(35 * MIN, t)).toBe("≈ 35m");
+  });
+
+  it("floors a tiny non-zero estimate to 5m, never 0", () => {
+    expect(formatHeadline(2 * MIN, t)).toBe("≈ 5m");
+  });
+
+  it("empty string for zero (widget hidden)", () => {
+    expect(formatHeadline(0, t)).toBe("");
+  });
+});
+
+describe("formatDayTotal", () => {
+  it('renders "h m" and shows — for empty days', () => {
+    expect(formatDayTotal(3 * 60 * MIN + 17 * MIN, t)).toBe("3h 17m");
+    expect(formatDayTotal(0, t)).toBe("—");
+  });
+});
+
+describe("formatGapMinutes", () => {
+  it("converts the tGap ms threshold to whole minutes", () => {
+    expect(formatGapMinutes(15 * MIN)).toBe(15);
+  });
+});

apps/client/src/features/page-history/work-time/format-work-time.ts

@@ -0,0 +1,45 @@
+// #395 — display formatting for the work-time estimate. Pure functions that take
+// a translator so ru-RU / en-US wording lives in the i18n catalogue and the
+// rounding logic stays unit-testable.
+
+type Translate = (key: string, opts?: Record<string, unknown>) => string;
+
+const MIN = 60 * 1000;
+
+function hm(totalMinutes: number): { hours: number; minutes: number } {
+  return {
+    hours: Math.floor(totalMinutes / 60),
+    minutes: totalMinutes % 60,
+  };
+}
+
+/**
+ * Headline number (§6.1): an ESTIMATE, so rounded to a coarse 5-minute step and
+ * prefixed with "≈". A non-zero-but-tiny estimate floors to 5m rather than
+ * rounding down to "0" (which would read as "no work"). Zero → empty string
+ * (the caller hides the widget).
+ */
+export function formatHeadline(workMs: number, t: Translate): string {
+  if (workMs <= 0) return "";
+  let minutes = Math.round(workMs / MIN / 5) * 5;
+  if (minutes === 0) minutes = 5;
+  const { hours, minutes: m } = hm(minutes);
+  if (hours > 0 && m > 0) return t("≈ {{hours}}h {{minutes}}m", { hours, minutes: m });
+  if (hours > 0) return t("≈ {{hours}}h", { hours });
+  return t("≈ {{minutes}}m", { minutes: m });
+}
+
+/** Per-day sum (§6.2), rounded to the minute. Zero → "—". */
+export function formatDayTotal(activeMs: number, t: Translate): string {
+  if (activeMs <= 0) return "—";
+  const minutes = Math.max(1, Math.round(activeMs / MIN));
+  const { hours, minutes: m } = hm(minutes);
+  if (hours > 0 && m > 0) return t("{{hours}}h {{minutes}}m", { hours, minutes: m });
+  if (hours > 0) return t("{{hours}}h", { hours });
+  return t("{{minutes}}m", { minutes: m });
+}
+
+/** The inactivity threshold, for the "estimate · gap = N min" caption. */
+export function formatGapMinutes(tGapMs: number): number {
+  return Math.round(tGapMs / MIN);
+}

apps/client/src/features/page-history/work-time/use-page-work-time.ts

@@ -0,0 +1,25 @@
+import { useQuery, UseQueryResult } from "@tanstack/react-query";
+import { IPageWorkTime } from "./work-time.types";
+import { getPageWorkTime, viewerTimezone } from "./work-time-service";
+
+const WORK_TIME_STALE_TIME = 5 * 60 * 1000;
+
+/**
+ * #395 — the "time worked on this article" estimate + per-day punch-card
+ * buckets. The buckets are computed server-side in the viewer's timezone (so a
+ * midnight-crossing session lands on the right calendar day for the reader).
+ * `enabled` is opt-in so the (cheap but non-trivial) projection query only fires
+ * when the number is actually shown.
+ */
+export function usePageWorkTime(
+  pageId: string,
+  enabled = true,
+): UseQueryResult<IPageWorkTime, Error> {
+  const tz = viewerTimezone();
+  return useQuery({
+    queryKey: ["page-work-time", pageId, tz],
+    queryFn: () => getPageWorkTime(pageId, tz),
+    enabled: enabled && !!pageId,
+    staleTime: WORK_TIME_STALE_TIME,
+  });
+}

apps/client/src/features/page-history/work-time/work-time-adapter.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildRows,
+  formatBlockTooltip,
+  summaryLabels,
+  toBlocks,
+  toTimelineDay,
+  EMPTY_RUN_COLLAPSE,
+} from "./work-time-adapter";
+import { IPageWorkTime, IPerDay } from "./work-time.types";
+
+const MIN = 60 * 1000;
+const HOUR = 60 * MIN;
+const DAY_MS = 24 * HOUR;
+
+// Fake translator: renders the key with {{tokens}} substituted, so the tests
+// assert the mapping/branching without depending on the i18n catalogue.
+const t = (key: string, opts?: Record<string, unknown>) =>
+  key.replace(/\{\{(\w+)\}\}/g, (_, k) => String(opts?.[k] ?? ""));
+
+// A day midnight anchored at a fixed UTC instant (tz handled server-side; we
+// only lay out fractions of the day the server already bucketed).
+const DAY0 = Date.UTC(2026, 5, 29, 0, 0, 0); // Mon 29 Jun 2026 00:00 UTC
+
+function day(over: Partial<IPerDay> & { day: number }): IPerDay {
+  return {
+    dayISO: new Date(over.day).toISOString().slice(0, 10),
+    activeMs: 0,
+    agentMs: 0,
+    windows: [],
+    ...over,
+  };
+}
+
+const config: IPageWorkTime["config"] = {
+  tGap: 15 * MIN,
+  agentTGap: 15 * MIN,
+  pIn: 0,
+  pOut: 0,
+  pSingle: 30 * 1000,
+  excludeGit: false,
+  dedupRoundMs: 1000,
+};
+
+function payload(over: Partial<IPageWorkTime>): IPageWorkTime {
+  return {
+    workMs: 0,
+    agentOnlyMs: 0,
+    perDay: [],
+    config,
+    tz: "UTC",
+    ...over,
+  };
+}
+
+describe("toBlocks", () => {
+  it("maps work+agent windows to time-of-day segments (hour fractions)", () => {
+    const d = day({
+      day: DAY0,
+      activeMs: 90 * MIN,
+      windows: [
+        { start: DAY0 + 9 * HOUR, end: DAY0 + 10 * HOUR + 30 * MIN, class: "work" },
+        { start: DAY0 + 22 * HOUR, end: DAY0 + 23 * HOUR, class: "agent_only" },
+      ],
+    });
+    const blocks = toBlocks(d);
+    expect(blocks).toHaveLength(2);
+    expect(blocks[0]).toMatchObject({ start: 9, end: 10.5, kind: "work" });
+    expect(blocks[1]).toMatchObject({ start: 22, end: 23, kind: "agent" });
+    // real epoch preserved for the DST-safe tooltip
+    expect(blocks[0].startEpoch).toBe(DAY0 + 9 * HOUR);
+  });
+
+  it("clamps out-of-day fractions to [0,24]", () => {
+    const d = day({
+      day: DAY0,
+      windows: [{ start: DAY0 - HOUR, end: DAY0 + 25 * HOUR, class: "work" }],
+    });
+    const [b] = toBlocks(d);
+    expect(b.start).toBe(0);
+    expect(b.end).toBe(24);
+  });
+});
+
+describe("toTimelineDay", () => {
+  it("draws the now-line only on today's row", () => {
+    const today = day({ day: DAY0, activeMs: HOUR });
+    const noon = DAY0 + 12 * HOUR;
+    const asToday = toTimelineDay(today, t, noon);
+    expect(asToday.isToday).toBe(true);
+    expect(asToday.nowFraction).toBeCloseTo(0.5, 5);
+
+    const past = day({ day: DAY0 - DAY_MS, activeMs: HOUR });
+    const asPast = toTimelineDay(past, t, noon);
+    expect(asPast.isToday).toBe(false);
+    expect(asPast.nowFraction).toBeUndefined();
+  });
+
+  it("labels an empty day and totals it as —", () => {
+    const empty = day({ day: DAY0 });
+    const d = toTimelineDay(empty, t, DAY0 + 12 * HOUR);
+    expect(d.isEmpty).toBe(true);
+    expect(d.totalLabel).toBe("—");
+  });
+});
+
+describe("buildRows (empty-run collapsing)", () => {
+  it("collapses a run of >= EMPTY_RUN_COLLAPSE empty days in place", () => {
+    const perDay: IPerDay[] = [
+      day({ day: DAY0, activeMs: HOUR }),
+      ...Array.from({ length: EMPTY_RUN_COLLAPSE }, (_, i) =>
+        day({ day: DAY0 + (i + 1) * DAY_MS }),
+      ),
+      day({ day: DAY0 + (EMPTY_RUN_COLLAPSE + 1) * DAY_MS, activeMs: HOUR }),
+    ];
+    const rows = buildRows(perDay, t, 0);
+    expect(rows.map((r) => r.type)).toEqual(["day", "gap", "day"]);
+    const gap = rows[1];
+    expect(gap.type === "gap" && gap.count).toBe(EMPTY_RUN_COLLAPSE);
+  });
+
+  it("keeps a short empty run as individual dimmed day rows", () => {
+    const perDay: IPerDay[] = [
+      day({ day: DAY0, activeMs: HOUR }),
+      day({ day: DAY0 + DAY_MS }),
+      day({ day: DAY0 + 2 * DAY_MS, activeMs: HOUR }),
+    ];
+    const rows = buildRows(perDay, t, 0);
+    expect(rows.map((r) => r.type)).toEqual(["day", "day", "day"]);
+  });
+});
+
+describe("summaryLabels", () => {
+  it("derives totalLabel/agentLabel from ms via the shared formatter", () => {
+    const { total, agent } = summaryLabels(
+      payload({ workMs: 4 * HOUR + 27 * MIN, agentOnlyMs: 80 * MIN }),
+      t,
+    );
+    expect(total).toBe("≈ 4h 25m");
+    expect(agent).toBe("≈ 1h 20m");
+  });
+
+  it("agent-only page: agent estimate fills the main slot, no secondary line", () => {
+    const { total, agent } = summaryLabels(
+      payload({ workMs: 0, agentOnlyMs: 80 * MIN }),
+      t,
+    );
+    expect(total).toBe("agent: ≈ 1h 20m");
+    expect(agent).toBeUndefined();
+  });
+
+  it("human-only page: no agent line", () => {
+    const { agent } = summaryLabels(payload({ workMs: HOUR, agentOnlyMs: 0 }), t);
+    expect(agent).toBeUndefined();
+  });
+});
+
+describe("formatBlockTooltip", () => {
+  it("formats start–end from the real epoch in the data tz + duration", () => {
+    const d = day({
+      day: DAY0,
+      windows: [{ start: DAY0 + 9 * HOUR, end: DAY0 + 10 * HOUR + 30 * MIN, class: "work" }],
+    });
+    const [b] = toBlocks(d);
+    const label = formatBlockTooltip(b, "UTC", "en-US", t);
+    expect(label).toBe("09:00 – 10:30 · 1h 30m");
+  });
+});

apps/client/src/features/page-history/work-time/work-time-adapter.ts

@@ -0,0 +1,168 @@
+// #566 — adapter: real IPageWorkTime → the render-ready shape the redesigned
+// time-of-day timeline consumes. The visual prototype (NewDesign/TimeWorkedModal)
+// was written against invented props (`DaySummary[]`, pre-made `totalLabel`); the
+// real payload is IPageWorkTime. Everything below is pure so the mapping (windows
+// → time-of-day blocks, ms → labels, the "now" boundary, empty-run collapsing) is
+// unit-testable without React. No re-bucketing: the server already grouped the
+// windows by the request timezone — we only lay out the windows it returned.
+
+import { IPageWorkTime, IPerDay, IDayWindow } from "./work-time.types";
+import { formatDayTotal, formatHeadline } from "./format-work-time";
+
+type Translate = (key: string, opts?: Record<string, unknown>) => string;
+
+export const DAY_MS = 24 * 60 * 60 * 1000;
+// Collapse a run of this many (or more) consecutive edit-free days into a single
+// "× N days" separator (§6.2 long-range) — preserved from the original punch-card.
+export const EMPTY_RUN_COLLAPSE = 8;
+
+export interface TimelineBlock {
+  /** Hour fraction 0..24 within the day — drives left/width positioning. */
+  start: number;
+  end: number;
+  kind: "work" | "agent";
+  /** Real epoch ms, kept for a DST-safe tooltip (formatted in the data tz). */
+  startEpoch: number;
+  endEpoch: number;
+}
+
+export interface TimelineDay {
+  key: string;
+  label: string;
+  totalLabel: string;
+  blocks: TimelineBlock[];
+  isEmpty: boolean;
+  /** Today lives only in the last active bucket; drives the "now" boundary. */
+  isToday: boolean;
+  /** 0..1 position of "now" within today's track (undefined when not today). */
+  nowFraction?: number;
+}
+
+export type TimelineRow =
+  | { type: "day"; day: TimelineDay }
+  | { type: "gap"; count: number };
+
+/** Weekday-day-month heading in the browser locale (matches the server tz
+ *  bucketing, since usePageWorkTime requests buckets in the viewer tz). */
+export function dayHeading(day: number): string {
+  return new Date(day).toLocaleDateString(undefined, {
+    weekday: "short",
+    day: "numeric",
+    month: "short",
+  });
+}
+
+/** Map one day's absolute windows into time-of-day blocks. `class` work|agent_only
+ *  → kind work|agent; positions are the in-day hour fraction (epoch kept for the
+ *  tooltip). Fractions are clamped to [0,24] to match the original punch-card. */
+export function toBlocks(day: IPerDay): TimelineBlock[] {
+  return day.windows.map((w: IDayWindow) => {
+    const start = clampHour((w.start - day.day) / (DAY_MS / 24));
+    const end = clampHour((w.end - day.day) / (DAY_MS / 24));
+    return {
+      start,
+      end,
+      kind: w.class === "work" ? "work" : "agent",
+      startEpoch: w.start,
+      endEpoch: w.end,
+    };
+  });
+}
+
+function clampHour(h: number): number {
+  return Math.max(0, Math.min(24, h));
+}
+
+/** Build a single render-ready day. `now` is injected for testability; the
+ *  "now" boundary is drawn only when `now` falls inside this bucket's calendar
+ *  day (so it appears on today's row and only when today has edits). */
+export function toTimelineDay(
+  day: IPerDay,
+  t: Translate,
+  now: number,
+): TimelineDay {
+  const isToday = now >= day.day && now < day.day + DAY_MS;
+  return {
+    key: day.dayISO,
+    label: dayHeading(day.day),
+    totalLabel: formatDayTotal(day.activeMs, t),
+    blocks: toBlocks(day),
+    isEmpty: day.activeMs === 0 && day.agentMs === 0,
+    isToday,
+    nowFraction: isToday ? (now - day.day) / DAY_MS : undefined,
+  };
+}
+
+/** Collapse long edit-free runs (≥ EMPTY_RUN_COLLAPSE) into an in-place "gap"
+ *  row; short runs stay as (dimmed, "—") day rows. Preserved from the original
+ *  punch-card so a page edited over months does not render hundreds of rows. */
+export function buildRows(
+  perDay: IPerDay[],
+  t: Translate,
+  now: number,
+): TimelineRow[] {
+  const rows: TimelineRow[] = [];
+  let emptyRun: IPerDay[] = [];
+  const flush = () => {
+    if (emptyRun.length >= EMPTY_RUN_COLLAPSE) {
+      rows.push({ type: "gap", count: emptyRun.length });
+    } else {
+      for (const d of emptyRun) {
+        rows.push({ type: "day", day: toTimelineDay(d, t, now) });
+      }
+    }
+    emptyRun = [];
+  };
+  for (const d of perDay) {
+    if (d.activeMs === 0 && d.agentMs === 0) {
+      emptyRun.push(d);
+    } else {
+      flush();
+      rows.push({ type: "day", day: toTimelineDay(d, t, now) });
+    }
+  }
+  flush();
+  return rows;
+}
+
+/** The big summary slot. Fail-safe for an agent-only page (#395/#551): since
+ *  formatHeadline(0) === "", never leave the 22px slot empty — put the agent
+ *  estimate in the main slot, and only show the secondary `agent:` line when
+ *  BOTH a human and an agent estimate exist. */
+export function summaryLabels(
+  data: IPageWorkTime,
+  t: Translate,
+): { total: string; agent?: string } {
+  const total =
+    data.workMs > 0
+      ? formatHeadline(data.workMs, t)
+      : t("agent: {{value}}", { value: formatHeadline(data.agentOnlyMs, t) });
+  const agent =
+    data.workMs > 0 && data.agentOnlyMs > 0
+      ? formatHeadline(data.agentOnlyMs, t)
+      : undefined;
+  return { total, agent };
+}
+
+/** Block hover label "start – end · duration". Times come from the REAL epoch
+ *  rendered in the data tz (NOT the 24h fraction) so a DST-transition day does
+ *  not skew the shown clock time. Duration reuses formatDayTotal (always > 0
+ *  here, so never "—"). */
+export function formatBlockTooltip(
+  block: TimelineBlock,
+  tz: string,
+  locale: string,
+  t: Translate,
+): string {
+  const fmt = new Intl.DateTimeFormat(locale || undefined, {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    timeZone: tz,
+  });
+  return t("{{start}} – {{end}} · {{duration}}", {
+    start: fmt.format(block.startEpoch),
+    end: fmt.format(block.endEpoch),
+    duration: formatDayTotal(block.endEpoch - block.startEpoch, t),
+  });
+}

apps/client/src/features/page-history/work-time/work-time-punch-card.tsx

@@ -0,0 +1,196 @@
+// #566 — redesigned "Time worked" body: daily time-of-day timelines. Each day is
+// a 24h track showing WHEN the work happened — a sticky 00/06/12/18/24 hour axis,
+// shaded night hours, per-block hover tooltip ("start – end · duration"), and a
+// "now" boundary on today's row. Presentation ported from NewDesign/TimeWorkedModal;
+// all data comes through the pure adapter over the real IPageWorkTime (zero backend
+// change). Positioning math, empty-run collapsing and the formatters are reused.
+import { Box, Group, ScrollArea, Stack, Text, Tooltip } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import { useMemo } from "react";
+import { IPageWorkTime } from "./work-time.types";
+import { formatGapMinutes } from "./format-work-time";
+import {
+  buildRows,
+  formatBlockTooltip,
+  summaryLabels,
+  TimelineBlock,
+  TimelineDay,
+} from "./work-time-adapter";
+import classes from "./work-time.module.css";
+
+// Minimum visible width so a very short session neither vanishes nor fakes dense
+// work (§6.2); kept from the original punch-card.
+const MIN_BLOCK_WIDTH_PCT = 0.6;
+
+function ActivityBlock({
+  block,
+  tz,
+  locale,
+}: {
+  block: TimelineBlock;
+  tz: string;
+  locale: string;
+}) {
+  const { t } = useTranslation();
+  const left = (block.start / 24) * 100;
+  const width = Math.max(((block.end - block.start) / 24) * 100, MIN_BLOCK_WIDTH_PCT);
+  const cls = [
+    classes.window,
+    block.kind === "work" ? classes.windowWork : classes.windowAgent,
+  ].join(" ");
+  return (
+    <Tooltip
+      label={formatBlockTooltip(block, tz, locale, t)}
+      withArrow
+      openDelay={120}
+      fz={11}
+    >
+      <div className={cls} style={{ left: `${left}%`, width: `${width}%` }} />
+    </Tooltip>
+  );
+}
+
+function DayTrack({
+  day,
+  tz,
+  locale,
+}: {
+  day: TimelineDay;
+  tz: string;
+  locale: string;
+}) {
+  return (
+    <div className={classes.row}>
+      <span className={classes.dayLabel}>{day.label}</span>
+      <div className={`${classes.track} ${day.isEmpty ? classes.trackEmpty : ""}`}>
+        {[25, 50, 75].map((p) => (
+          <div key={p} className={classes.hourTick} style={{ left: `${p}%` }} />
+        ))}
+        {day.blocks.map((b, i) => (
+          <ActivityBlock key={i} block={b} tz={tz} locale={locale} />
+        ))}
+        {day.isToday && day.nowFraction != null && (
+          <div
+            className={classes.nowLine}
+            style={{ left: `${day.nowFraction * 100}%` }}
+          />
+        )}
+      </div>
+      <span
+        className={classes.daySum}
+        data-empty={day.totalLabel === "—" ? true : undefined}
+      >
+        {day.totalLabel}
+      </span>
+    </div>
+  );
+}
+
+interface Props {
+  data: IPageWorkTime;
+}
+
+export default function WorkTimePunchCard({ data }: Props) {
+  const { t, i18n } = useTranslation();
+  const locale = i18n.language;
+  const now = Date.now();
+  const rows = useMemo(
+    () => buildRows(data.perDay, t, now),
+    // `now` intentionally re-read on each open; excluded so the memo tracks data.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [data.perDay, t],
+  );
+  const { total, agent } = summaryLabels(data, t);
+  const gapMin = formatGapMinutes(data.config.tGap);
+
+  if (data.workMs <= 0 && data.agentOnlyMs <= 0) {
+    return (
+      <Text size="sm" c="dimmed" py="md">
+        {t("No editing activity recorded yet.")}
+      </Text>
+    );
+  }
+
+  return (
+    <Stack gap="xs">
+      {/* summary */}
+      <Group align="baseline" gap="md">
+        <Text fz={22} fw={700}>
+          {total}
+        </Text>
+        {agent && (
+          <Text size="xs" c="dimmed">
+            {t("agent: {{value}}", { value: agent })}
+          </Text>
+        )}
+      </Group>
+
+      {/* legend */}
+      <Group gap="md">
+        <Text size="xs" c="dimmed">
+          <span
+            className={`${classes.legendSwatch} ${classes.windowWork}`}
+            style={{ marginRight: 4 }}
+          />
+          {t("Work")}
+        </Text>
+        <Text size="xs" c="dimmed">
+          <span
+            className={`${classes.legendSwatch} ${classes.windowAgent}`}
+            style={{ marginRight: 4 }}
+          />
+          {t("Agent")}
+        </Text>
+      </Group>
+
+      {/* sticky hour axis */}
+      <div className={`${classes.row} ${classes.axisRow}`}>
+        <span />
+        <div className={classes.axis}>
+          {[
+            ["0%", "00", "start"],
+            ["25%", "06", "center"],
+            ["50%", "12", "center"],
+            ["75%", "18", "center"],
+            ["100%", "24", "end"],
+          ].map(([l, label, align]) => (
+            <span
+              key={label}
+              className={classes.axisTick}
+              data-align={align}
+              style={{ left: l }}
+            >
+              {label}
+            </span>
+          ))}
+        </div>
+        <span />
+      </div>
+
+      {/* day rows */}
+      <ScrollArea.Autosize mah="60vh" type="hover">
+        {rows.map((row, i) =>
+          row.type === "day" ? (
+            <DayTrack
+              key={row.day.key}
+              day={row.day}
+              tz={data.tz}
+              locale={locale}
+            />
+          ) : (
+            <Box key={`gap-${i}`} className={classes.gapRow}>
+              {t("× {{count}} days without edits", { count: row.count })}
+            </Box>
+          ),
+        )}
+      </ScrollArea.Autosize>
+
+      <Text size="xs" c="dimmed" mt="xs">
+        {t("Estimate · timezone {{tz}} · inactivity gap {{gap}} min", {
+          tz: data.tz,
+          gap: gapMin,
+        })}
+      </Text>
+    </Stack>
+  );
+}

apps/client/src/features/page-history/work-time/work-time-service.ts

@@ -0,0 +1,23 @@
+import api from "@/lib/api-client";
+import { IPageWorkTime } from "./work-time.types";
+
+/** The viewer's IANA timezone (browser locale) — the punch-card lays days out
+ *  in "my evenings", per §6.3/§10. Falls back to UTC if the runtime hides it. */
+export function viewerTimezone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+export async function getPageWorkTime(
+  pageId: string,
+  tz: string,
+): Promise<IPageWorkTime> {
+  const req = await api.post<IPageWorkTime>("/pages/history/time", {
+    pageId,
+    tz,
+  });
+  return req.data;
+}

apps/client/src/features/page-history/work-time/work-time-stat.tsx

@@ -0,0 +1,69 @@
+import { Modal, Text, Tooltip, UnstyledButton } from "@mantine/core";
+import { useDisclosure } from "@mantine/hooks";
+import { IconClockHour4 } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { usePageWorkTime } from "./use-page-work-time";
+import { formatGapMinutes, formatHeadline } from "./format-work-time";
+import WorkTimePunchCard from "./work-time-punch-card";
+
+interface Props {
+  pageId: string;
+}
+
+/**
+ * #395 — the clickable "time worked on this article" headline (§6.1). Renders
+ * the `work` estimate with a "≈" sign and the inactivity threshold in a tooltip
+ * (it is an estimate, not a stopwatch). Clicking opens the daily punch-card
+ * (§6.2). Renders nothing until there is a non-zero human OR agent estimate, so a
+ * brand-new / never-edited page shows no widget. For an agent-only-edited page
+ * (workMs===0, agentOnlyMs>0) the headline shows the agent estimate (labelled
+ * `agent:`, matching the punch-card) so the punch-card stays reachable (#395:
+ * "how much a HUMAN and separately the AGENT").
+ */
+export default function WorkTimeStat({ pageId }: Props) {
+  const { t } = useTranslation();
+  const [opened, { open, close }] = useDisclosure(false);
+  const { data } = usePageWorkTime(pageId);
+
+  if (!data || (data.workMs <= 0 && data.agentOnlyMs <= 0)) return null;
+
+  const agentOnly = data.workMs <= 0;
+  const label = agentOnly
+    ? t("agent: {{value}}", { value: formatHeadline(data.agentOnlyMs, t) })
+    : formatHeadline(data.workMs, t);
+  const gapMin = formatGapMinutes(data.config.tGap);
+
+  return (
+    <>
+      <Tooltip
+        label={t("Estimated time worked (inactivity gap {{gap}} min)", {
+          gap: gapMin,
+        })}
+        position="bottom"
+      >
+        <UnstyledButton
+          onClick={open}
+          aria-label={t("Show time worked on this page")}
+        >
+          <Text
+            size="xs"
+            c="dimmed"
+            style={{ display: "inline-flex", alignItems: "center", gap: 4 }}
+          >
+            <IconClockHour4 size={14} />
+            {label}
+          </Text>
+        </UnstyledButton>
+      </Tooltip>
+
+      <Modal
+        opened={opened}
+        onClose={close}
+        title={t("Time worked on this article")}
+        size="46rem"
+      >
+        <WorkTimePunchCard data={data} />
+      </Modal>
+    </>
+  );
+}

apps/client/src/features/page-history/work-time/work-time.module.css

@@ -0,0 +1,136 @@
+/* #566 — time-of-day timeline. Custom CSS segments on a fixed 24-hour track
+   (position = offset-in-day / 24h, width = duration / 24h), no chart library.
+   Night hours (0–6, 21–24) are shaded so the eye reads morning-vs-evening; a
+   sticky hour axis labels 00/06/12/18/24. Theme-aware via Mantine tokens. */
+
+.row {
+  display: grid;
+  grid-template-columns: 96px 1fr 64px;
+  align-items: center;
+  gap: 12px;
+  padding: 3px 0;
+}
+
+.dayLabel {
+  font-size: var(--mantine-font-size-xs);
+  color: var(--mantine-color-dimmed);
+  white-space: nowrap;
+}
+
+.track {
+  --wt-night: rgba(90, 100, 130, 0.16);
+  --wt-day: rgba(90, 100, 130, 0.03);
+  position: relative;
+  height: 20px;
+  border-radius: 5px;
+  overflow: hidden;
+  /* base fill + night shading: 0–6h and 21–24h (87.5%) darker than daytime */
+  background:
+    linear-gradient(
+      90deg,
+      var(--wt-night) 0 25%,
+      var(--wt-day) 25% 87.5%,
+      var(--wt-night) 87.5% 100%
+    ),
+    light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-6));
+}
+
+/* Short (< EMPTY_RUN_COLLAPSE) edit-free days: dimmed, empty track. */
+.trackEmpty {
+  opacity: 0.5;
+}
+
+/* Quarter-day grid divisions (06/12/18) inside the track. */
+.hourTick {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 1px;
+  background-color: light-dark(
+    var(--mantine-color-gray-3),
+    var(--mantine-color-dark-4)
+  );
+}
+
+.window {
+  position: absolute;
+  top: 3px;
+  height: 14px;
+  border-radius: 3px;
+  min-width: 3px;
+  cursor: default;
+}
+
+.windowWork {
+  background-color: var(--mantine-color-blue-5);
+}
+
+.windowAgent {
+  background-color: var(--mantine-color-grape-5);
+}
+
+/* The "now" boundary on today's row. */
+.nowLine {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background-color: var(--mantine-color-red-6);
+}
+
+.daySum {
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
+  text-align: right;
+  white-space: nowrap;
+}
+
+.daySum[data-empty] {
+  color: var(--mantine-color-dimmed);
+  font-weight: 400;
+}
+
+/* Sticky hour axis header aligned to the track column. */
+.axisRow {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background-color: var(--mantine-color-body);
+  padding-bottom: 2px;
+}
+
+.axis {
+  position: relative;
+  height: 14px;
+}
+
+.axisTick {
+  position: absolute;
+  top: 0;
+  font-size: 10px;
+  font-weight: 500;
+  color: var(--mantine-color-dimmed);
+}
+
+.axisTick[data-align="center"] {
+  transform: translateX(-50%);
+}
+
+.axisTick[data-align="end"] {
+  transform: translateX(-100%);
+}
+
+.gapRow {
+  padding: 6px 0 6px 108px;
+  font-size: var(--mantine-font-size-xs);
+  color: var(--mantine-color-dimmed);
+  font-style: italic;
+}
+
+.legendSwatch {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+  vertical-align: middle;
+}

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

@@ -0,0 +1,37 @@
+// #395 — client-side mirror of the server work-time payload
+// (apps/server/src/core/page/work-time). Shapes returned by POST /pages/history/time.
+
+export type WorkSessionClass = "work" | "agent_only";
+
+export interface IDayWindow {
+  start: number;
+  end: number;
+  class: WorkSessionClass;
+}
+
+export interface IPerDay {
+  day: number;
+  dayISO: string;
+  activeMs: number;
+  agentMs: number;
+  windows: IDayWindow[];
+}
+
+export interface IWorkTimeConfig {
+  tGap: number;
+  agentTGap: number;
+  pIn: number;
+  pOut: number;
+  pSingle: number;
+  excludeGit: boolean;
+  burstCapMs?: number;
+  dedupRoundMs: number;
+}
+
+export interface IPageWorkTime {
+  workMs: number;
+  agentOnlyMs: number;
+  perDay: IPerDay[];
+  config: IWorkTimeConfig;
+  tz: string;
+}

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

@@ -51,6 +51,7 @@ import {
 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";
+import WorkTimeStat from "@/features/page-history/work-time/work-time-stat.tsx";
 import { useTimeAgo } from "@/hooks/use-time-ago.tsx";
 import {
   useFavoriteIds,
@@ -265,6 +266,8 @@ function PageActionMenu({ readOnly, onSaveVersion }: PageActionMenuProps) {
 
   return (
     <>
+      {page?.id && <WorkTimeStat pageId={page.id} />}
+
       <Menu
         shadow="xl"
         position="bottom-end"

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

@@ -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,

apps/client/src/features/page/tree/model/tree-model.test.ts

@@ -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"]);
   });
 

apps/client/src/features/page/tree/model/tree-model.ts

@@ -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,

apps/client/src/features/search/components/search-spotlight.tsx

@@ -1,6 +1,6 @@
 import { Spotlight } from "@mantine/spotlight";
 import { IconSearch } from "@tabler/icons-react";
-import { Group, VisuallyHidden } from "@mantine/core";
+import { Group, Text, VisuallyHidden } from "@mantine/core";
 import { useState, useMemo } from "react";
 import { useDebouncedValue } from "@mantine/hooks";
 import { useTranslation } from "react-i18next";
@@ -84,6 +84,11 @@ export function SearchSpotlight({ spaceId }: SearchSpotlightProps) {
             onFiltersChange={handleFiltersChange}
             spaceId={spaceId}
           />
+          {/* #529: operator hint — matches ANY word by default; "…" for an exact
+              phrase, +term to require, -term to exclude. */}
+          <Text size="xs" c="dimmed" mt={4}>
+            {t('Tip: "exact phrase", +required, -excluded')}
+          </Text>
         </div>
 
         <VisuallyHidden role="status" aria-live="polite">

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

@@ -5,6 +5,9 @@ import { IPage } from "@/features/page/types/page.types.ts";
 
 export interface IPageSearch {
   id: string;
+  // #529 A7 superset: `pageId` aliases `id`; `rank`/`highlight` are null for
+  // substring-only hits (the UI already falls back to the title/snippet).
+  pageId?: string;
   title: string;
   icon: string;
   parentPageId: string;
@@ -12,9 +15,36 @@ export interface IPageSearch {
   creatorId: string;
   createdAt: Date;
   updatedAt: Date;
-  rank: string;
-  highlight: string;
+  rank: string | number | null;
+  highlight: string | null;
   space: Partial<ISpace>;
+  // New #529 fields (present from the native Postgres search driver).
+  snippet?: string;
+  score?: number;
+  path?: string[];
+  matchedFields?: string[];
+  matchedTerms?: string[];
+}
+
+// #529 A5 pagination envelope returned by POST /search (native driver). The web
+// list helpers read `items`; these travel alongside for pagination + diagnostics.
+export interface IPageSearchResponse {
+  items: IPageSearch[];
+  total: number;
+  hasMore: boolean;
+  truncatedAtCap: boolean;
+  offset: number;
+  query?: {
+    raw: string;
+    parsed: {
+      positive: string[];
+      required: string[];
+      excluded: string[];
+      reason?: string;
+    };
+    mode: "or" | "and";
+    match: string;
+  };
 }
 
 export interface SearchSuggestionParams {
@@ -37,6 +67,10 @@ export interface IPageSearchParams {
   query: string;
   spaceId?: string;
   shareId?: string;
+  // #529 A9: match mode (auto default) + pagination.
+  match?: "auto" | "word" | "prefix" | "substring";
+  limit?: number;
+  offset?: number;
 }
 
 export interface IAttachmentSearch {

apps/client/src/features/user/guarded-reload.test.tsx

@@ -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);
+  });
+});

apps/client/src/features/user/guarded-reload.tsx

@@ -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 = "";
+}

apps/client/src/features/user/reload-budget.integration.test.tsx

@@ -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();
+    }
+  });
+});

apps/client/src/features/user/user-provider.tsx

@@ -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();

apps/client/src/features/user/version-coherence.test.ts

@@ -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");
+  });
+});

apps/client/src/features/user/version-coherence.ts

@@ -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
+}

apps/client/src/features/websocket/tree-socket-reducers.test.ts

@@ -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).

apps/client/src/lib/reload-guard.test.ts

@@ -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);
+  });
+});

apps/client/src/lib/reload-guard.ts

@@ -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;
+  }
+}

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

@@ -36,6 +36,7 @@ const STATIC_ROUTES = new Set<string>([
   '/setup/register',
   '/settings/account/profile',
   '/settings/account/preferences',
+  '/settings/account/api-keys',
   '/settings/workspace',
   '/settings/ai',
   '/settings/members',

apps/client/src/pages/settings/account/account-api-keys.tsx

@@ -0,0 +1,22 @@
+import SettingsTitle from "@/components/settings/settings-title.tsx";
+import ApiKeysManager from "@/features/api-key/components/api-keys-manager";
+import { getAppName } from "@/lib/config.ts";
+import { Helmet } from "react-helmet-async";
+import { useTranslation } from "react-i18next";
+
+export default function AccountApiKeys() {
+  const { t } = useTranslation();
+
+  return (
+    <>
+      <Helmet>
+        <title>
+          {t("API keys")} - {getAppName()}
+        </title>
+      </Helmet>
+      <SettingsTitle title={t("API keys")} />
+
+      <ApiKeysManager />
+    </>
+  );
+}

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

@@ -14,9 +14,11 @@
  */
 
 /*
- * Push the top-anchored toast containers below the top chrome (fixed 45px
- * header + optional 45px format toolbar + ~6px gap) so a toast (z-index 10000)
- * neither covers nor intercepts clicks on the header/toolbar (both z-index 99).
+ * Anchor the top toast containers to the very top edge of the viewport (a small
+ * 8px gap), above the header/search chrome, per product request. The toast
+ * (z-index 10000) therefore renders over the header/toolbar (both z-index 99)
+ * for the few seconds it is visible — intentional, since it is the top-most,
+ * in-the-line-of-sight surface.
  *
  * Scoped to [data-position^='top'] on purpose. Mantine renders ALL SIX position
  * containers simultaneously (`position` only routes toasts into one via the
@@ -34,7 +36,7 @@
  * (the :where() contributes 0), regardless of stylesheet order.
  */
 .mantine-Notifications-root[data-position^='top'] {
-  top: 96px;
+  top: 8px;
 }
 
 [data-mantine-color-scheme='light'] .mantine-Notification-root {

apps/client/vite.config.ts

@@ -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({

apps/client/vitest.setup.ts

@@ -63,3 +63,15 @@ vi.stubGlobal("matchMedia", (query: string) => ({
   removeEventListener: vi.fn(),
   dispatchEvent: vi.fn(),
 }));
+
+// Mantine's ScrollArea (used by Table.ScrollContainer, ScrollArea, etc.) reads
+// `ResizeObserver` in a layout effect on mount, which jsdom does not implement.
+// A no-op stub lets any test rendering those components mount cleanly.
+vi.stubGlobal(
+  "ResizeObserver",
+  class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  },
+);

apps/server/package.json

@@ -23,7 +23,7 @@
     "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
     "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build && pnpm --filter @docmost/token-estimate build",
+    "pretest": "pnpm --filter @docmost/editor-ext build && pnpm --filter @docmost/prosemirror-markdown build && pnpm --filter @docmost/token-estimate build && pnpm --filter @docmost/mcp build",
     "test": "jest",
     "test:int": "jest --config test/jest-integration.json",
     "test:watch": "jest --watch",

apps/server/src/collaboration/collaboration.module.ts

@@ -16,6 +16,7 @@ import { TransclusionService } from '../core/page/transclusion/transclusion.serv
 import { TransclusionModule } from '../core/page/transclusion/transclusion.module';
 import { StorageModule } from '../integrations/storage/storage.module';
 import { EnvironmentModule } from '../integrations/environment/environment.module';
+import { ApiKeyModule } from '../core/api-key/api-key.module';
 
 @Module({
   providers: [
@@ -31,6 +32,7 @@ import { EnvironmentModule } from '../integrations/environment/environment.modul
   exports: [CollaborationGateway],
   imports: [
     TokenModule,
+    ApiKeyModule,
     WatcherModule,
     StorageModule.forRootAsync({
       imports: [EnvironmentModule],

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

@@ -141,7 +141,57 @@ export function htmlToJson(html: string) {
   }
 }
 
-export function jsonToText(tiptapJson: JSONContent) {
+/**
+ * Deterministic text-serializer overrides for the `format:"text"` page read
+ * (#502). Non-text nodes render to a STABLE placeholder instead of their
+ * (structure-dependent) inner text, so a machine diff of two text reads is
+ * driven only by the page's actual prose — output stability across package
+ * versions IS the contract (pinned by a snapshot test). Returning a string from
+ * a `textSerializer` also stops `generateText` descending into the node, so a
+ * table renders as ONE token rather than its flattened cell text.
+ *
+ * Only nodes with no meaningful flat-text form are overridden; every other node
+ * (paragraph/heading/list/code/blockquote/callout/…) keeps its natural text so
+ * a config written as markdown reads back byte-identical.
+ */
+const TEXT_READ_SERIALIZERS: Record<string, (props: { node: any }) => string> =
+  {
+    // Image atom: no inner text -> a fixed placeholder.
+    image: () => '[image]',
+    // Table: `[table RxC]` where R = row count, C = the first row's cell count
+    // (a table's columns are uniform per the schema). Computed from the PM node,
+    // so it is independent of cell contents.
+    table: ({ node }) => {
+      const rows = node?.childCount ?? 0;
+      const cols = rows > 0 ? (node.child(0)?.childCount ?? 0) : 0;
+      return `[table ${rows}x${cols}]`;
+    },
+  };
+
+/**
+ * Serialize a ProseMirror/TipTap document to plain text.
+ *
+ * Default (no options): the long-standing search-index behavior — bare
+ * concatenated node text with `generateText`'s default `\n\n` block separator.
+ * This feeds the page `textContent` tsvector and MUST NOT change.
+ *
+ * `deterministic:true` (#502 `format:"text"` page read): a flat, machine-diffable
+ * rendering — one line per block (`\n` block separator; `hardBreak` already
+ * serializes to `\n`), inline marks/anchors/autoformat dropped, and non-text
+ * nodes replaced by the stable placeholders above (`[image]`, `[table RxC]`).
+ */
+export function jsonToText(
+  // `any` (like jsonToHtml/jsonToMarkdown) so a loosely-typed DB `page.content`
+  // (JsonValue) can be passed straight through, as the controller does.
+  tiptapJson: any,
+  options?: { deterministic?: boolean },
+) {
+  if (options?.deterministic) {
+    return generateText(tiptapJson, tiptapExtensions, {
+      blockSeparator: '\n',
+      textSerializers: TEXT_READ_SERIALIZERS,
+    });
+  }
   return generateText(tiptapJson, tiptapExtensions);
 }
 

apps/server/src/collaboration/extensions/authentication.extension.spec.ts

@@ -52,6 +52,7 @@ describe('AuthenticationExtension.onAuthenticate', () => {
   let pageRepo: { findById: jest.Mock };
   let spaceMemberRepo: { getUserSpaceRoles: jest.Mock };
   let pagePermissionRepo: { canUserEditPage: jest.Mock };
+  let apiKeyService: { validate: jest.Mock };
 
   // Build the hocuspocus onAuthenticate payload. connectionConfig.readOnly
   // starts false; the extension flips it to true on a read-only downgrade.
@@ -79,12 +80,15 @@ describe('AuthenticationExtension.onAuthenticate', () => {
       }),
     };
 
+    apiKeyService = { validate: jest.fn().mockResolvedValue({ user: {}, workspace: {} }) };
+
     ext = new AuthenticationExtension(
       tokenService as any,
       userRepo as any,
       pageRepo as any,
       spaceMemberRepo as any,
       pagePermissionRepo as any,
+      apiKeyService as any,
     );
     // Silence the extension's logger (it warns/debugs on denial branches).
     jest.spyOn(ext['logger'], 'warn').mockImplementation(() => undefined);
@@ -231,4 +235,73 @@ describe('AuthenticationExtension.onAuthenticate', () => {
     // No internal ai_chats row for an MCP/service-account collab edit → null.
     expect(ctx.aiChatId).toBeNull();
   });
+
+  // --- #501: api-key laundering guard (fail-closed discriminator) ----------
+  describe('api-key laundering guard', () => {
+    it('api_key principal → row-checks the key on connect (valid key proceeds)', async () => {
+      tokenService.verifyJwt.mockResolvedValue(
+        buildJwt({ principal: 'api_key', apiKeyId: 'key-1' }),
+      );
+      const data = buildData();
+      await ext.onAuthenticate(data as any);
+
+      expect(apiKeyService.validate).toHaveBeenCalledTimes(1);
+      expect(apiKeyService.validate).toHaveBeenCalledWith(
+        expect.objectContaining({ apiKeyId: 'key-1', type: JwtType.API_KEY }),
+      );
+    });
+
+    it('REVOKED api_key → Unauthorized on connect, BEFORE any page/user lookup', async () => {
+      tokenService.verifyJwt.mockResolvedValue(
+        buildJwt({ principal: 'api_key', apiKeyId: 'key-1' }),
+      );
+      // The shared validator denies a revoked key.
+      apiKeyService.validate.mockRejectedValue(new UnauthorizedException());
+
+      await expect(ext.onAuthenticate(buildData() as any)).rejects.toThrow(
+        UnauthorizedException,
+      );
+      // No new collab connection: the key check gates before page access.
+      expect(pageRepo.findById).not.toHaveBeenCalled();
+    });
+
+    it('api_key principal missing apiKeyId → Unauthorized (malformed)', async () => {
+      tokenService.verifyJwt.mockResolvedValue(buildJwt({ principal: 'api_key' }));
+      await expect(ext.onAuthenticate(buildData() as any)).rejects.toThrow(
+        UnauthorizedException,
+      );
+      expect(apiKeyService.validate).not.toHaveBeenCalled();
+    });
+
+    it('session principal → NO api-key check (session-backed, incl. internal agent)', async () => {
+      tokenService.verifyJwt.mockResolvedValue(buildJwt({ principal: 'session' }));
+      await ext.onAuthenticate(buildData() as any);
+      expect(apiKeyService.validate).not.toHaveBeenCalled();
+    });
+
+    it('claimless token WITHIN the grace window → trusted (legacy pre-rollout)', async () => {
+      // Default rolloutAt = now, so we are inside the grace window.
+      tokenService.verifyJwt.mockResolvedValue(buildJwt()); // no principal
+      await expect(ext.onAuthenticate(buildData() as any)).resolves.toBeDefined();
+      expect(apiKeyService.validate).not.toHaveBeenCalled();
+    });
+
+    it('claimless token AFTER the grace window → Unauthorized (fail-closed)', async () => {
+      // Move the rollout reference far into the past so the grace has elapsed.
+      (ext as any).rolloutAt = Date.now() - 25 * 60 * 60 * 1000;
+      tokenService.verifyJwt.mockResolvedValue(buildJwt()); // no principal
+      await expect(ext.onAuthenticate(buildData() as any)).rejects.toThrow(
+        UnauthorizedException,
+      );
+    });
+
+    it('infra error from the api-key row-check propagates (not masked)', async () => {
+      tokenService.verifyJwt.mockResolvedValue(
+        buildJwt({ principal: 'api_key', apiKeyId: 'key-1' }),
+      );
+      const boom = new Error('db down');
+      apiKeyService.validate.mockRejectedValue(boom);
+      await expect(ext.onAuthenticate(buildData() as any)).rejects.toBe(boom);
+    });
+  });
 });

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

@@ -14,20 +14,37 @@ import { findHighestUserSpaceRole } from '@docmost/db/repos/space/utils';
 import { SpaceRole } from '../../common/helpers/types/permission';
 import { isUserDisabled } from '../../common/helpers';
 import { getPageId } from '../collaboration.util';
-import { JwtCollabPayload, JwtType } from '../../core/auth/dto/jwt-payload';
+import {
+  JwtApiKeyPayload,
+  JwtCollabPayload,
+  JwtType,
+} from '../../core/auth/dto/jwt-payload';
 import { resolveProvenance } from '../../common/decorators/auth-provenance.decorator';
 import { observeCollabAuth } from '../../integrations/metrics/metrics.registry';
+import { ApiKeyService } from '../../core/api-key/api-key.service';
+
+// Max lifetime of a collab token (generateCollabToken uses expiresIn '24h'). Used
+// as the rollout grace window below: once this long has elapsed since this
+// process started serving the #501 code, every STILL-VALID collab token was
+// necessarily minted post-rollout and MUST carry the `principal` discriminator,
+// so a claimless one is a bug and is rejected (fail-closed) rather than trusted.
+const COLLAB_TOKEN_GRACE_MS = 24 * 60 * 60 * 1000;
 
 @Injectable()
 export class AuthenticationExtension implements Extension {
   private readonly logger = new Logger(AuthenticationExtension.name);
 
+  // Reference instant for the claimless-rejection grace window. Overridable so a
+  // unit test can drive the pre-/post-grace boundary without wall-clock waits.
+  protected rolloutAt = Date.now();
+
   constructor(
     private tokenService: TokenService,
     private userRepo: UserRepo,
     private pageRepo: PageRepo,
     private readonly spaceMemberRepo: SpaceMemberRepo,
     private readonly pagePermissionRepo: PagePermissionRepo,
+    private readonly apiKeyService: ApiKeyService,
   ) {}
 
   async onAuthenticate(data: onAuthenticatePayload) {
@@ -54,6 +71,36 @@ export class AuthenticationExtension implements Extension {
       throw new UnauthorizedException('Invalid collab token');
     }
 
+    // #501 — fail-closed api-key laundering guard. A collab token minted by an
+    // api-key principal carries principal='api_key' + apiKeyId; re-check the key
+    // on connect so a REVOKED key gets NO new collab connections (a collab token
+    // outlives its 24h, but a revoked key can no longer open fresh ones). An
+    // api-key token missing its apiKeyId is malformed → reject. A claimless token
+    // (no recognized principal) is trusted only DURING the rollout grace window
+    // (a legacy pre-rollout session token, which api keys could never mint);
+    // once the grace has elapsed every valid token must carry the discriminator,
+    // so a claimless one is a bug and is rejected (not silently trusted for 24h).
+    const principal = jwtPayload.principal;
+    if (principal === 'api_key') {
+      if (!jwtPayload.apiKeyId) {
+        throw new UnauthorizedException();
+      }
+      // Row-check via the SHARED validator: throws Unauthorized on a revoked/
+      // expired/disabled key; an infra error propagates (not masked). No new
+      // connection for a dead key.
+      await this.apiKeyService.validate({
+        sub: jwtPayload.sub,
+        workspaceId: jwtPayload.workspaceId,
+        apiKeyId: jwtPayload.apiKeyId,
+        type: JwtType.API_KEY,
+      } as JwtApiKeyPayload);
+    } else if (principal !== 'session') {
+      // Unrecognized/absent discriminator: reject once past the grace window.
+      if (Date.now() - this.rolloutAt >= COLLAB_TOKEN_GRACE_MS) {
+        throw new UnauthorizedException();
+      }
+    }
+
     const userId = jwtPayload.sub;
     const workspaceId = jwtPayload.workspaceId;
 

apps/server/src/collaboration/json-to-text-deterministic.spec.ts

@@ -0,0 +1,116 @@
+import { jsonToText } from './collaboration.util';
+
+// #502 READ contract: `jsonToText(json, { deterministic: true })` — the flat,
+// machine-diffable text rendering behind getPage `format:"text"`. Block-per-line
+// (`\n` separator), inline marks/anchors dropped, hardBreak -> `\n`, and non-text
+// nodes replaced by STABLE placeholders (`[image]`, `[table RxC]`). Output
+// stability across package versions IS the contract, so it is pinned by a
+// snapshot below. The DEFAULT (no options) path is the search-index serializer
+// and MUST be unchanged — asserted separately.
+
+const doc = (...content: any[]) => ({ type: 'doc', content });
+const para = (...content: any[]) => ({ type: 'paragraph', content });
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+
+describe('jsonToText — default (search index) behavior is unchanged', () => {
+  it('uses the `\\n\\n` block separator and drops non-text nodes to empty', () => {
+    const d = doc(para(text('alpha')), para(text('beta')));
+    expect(jsonToText(d)).toBe('alpha\n\nbeta');
+  });
+
+  it('an image contributes no text in the default (tsvector) mode', () => {
+    const d = doc(para(text('cap')), { type: 'image', attrs: { src: 's' } });
+    // No `[image]` placeholder leaks into the search index.
+    expect(jsonToText(d)).not.toContain('[image]');
+  });
+});
+
+describe('jsonToText — deterministic:true (getPage format:"text")', () => {
+  it('renders one line per block with `\\n` separators, marks dropped', () => {
+    const d = doc(
+      { type: 'heading', attrs: { level: 2 }, content: [text('Title')] },
+      para(
+        text('hello ', [{ type: 'bold' }]),
+        text('world', [{ type: 'italic' }]),
+      ),
+    );
+    expect(jsonToText(d, { deterministic: true })).toBe('Title\nhello world');
+  });
+
+  it('a hardBreak renders as a newline', () => {
+    const d = doc(para(text('a'), { type: 'hardBreak' }, text('b')));
+    expect(jsonToText(d, { deterministic: true })).toBe('a\nb');
+  });
+
+  it('an image node -> the stable `[image]` placeholder', () => {
+    const d = doc(para(text('before')), { type: 'image', attrs: { src: 's' } });
+    expect(jsonToText(d, { deterministic: true })).toBe('before\n[image]');
+  });
+
+  it('a table -> `[table RxC]` (rows x columns) and its cell text is NOT flattened in', () => {
+    const cell = (t: string) => ({
+      type: 'tableCell',
+      content: [para(text(t))],
+    });
+    const row = (...cells: any[]) => ({ type: 'tableRow', content: cells });
+    const table = {
+      type: 'table',
+      content: [
+        row(cell('CELLONE'), cell('CELLTWO'), cell('CELLTHREE')),
+        row(cell('CELLFOUR'), cell('CELLFIVE'), cell('CELLSIX')),
+      ],
+    };
+    const d = doc(para(text('grid:')), table);
+    const out = jsonToText(d, { deterministic: true });
+    expect(out).toBe('grid:\n[table 2x3]');
+    expect(out).not.toContain('CELL'); // cell text is not flattened into the read
+  });
+
+  it('SNAPSHOT: a mixed document renders to a stable, deterministic string', () => {
+    const cell = (t: string) => ({
+      type: 'tableCell',
+      content: [para(text(t))],
+    });
+    const d = doc(
+      { type: 'heading', attrs: { level: 1 }, content: [text('Config')] },
+      para(text('key = ', [{ type: 'bold' }]), text('value')),
+      {
+        type: 'bulletList',
+        content: [
+          { type: 'listItem', content: [para(text('one'))] },
+          { type: 'listItem', content: [para(text('two'))] },
+        ],
+      },
+      { type: 'image', attrs: { src: 's' } },
+      {
+        type: 'table',
+        content: [{ type: 'tableRow', content: [cell('x'), cell('y')] }],
+      },
+    );
+    expect(jsonToText(d, { deterministic: true })).toMatchInlineSnapshot(`
+     "Config
+     key = value
+
+
+     one
+
+     two
+     [image]
+     [table 1x2]"
+    `);
+  });
+
+  it('SCENARIO: a config written as a code block reads back byte-identical (diff empty)', () => {
+    const config =
+      'export TICKET_LIFETIME=$2592000\nservers:\n  - www.internal.host';
+    const d = doc({
+      type: 'codeBlock',
+      attrs: { language: 'yaml' },
+      content: [text(config)],
+    });
+    // The code block is one block; its text (dollars, bare domain, newlines) is
+    // preserved verbatim, so a read-as-text of a stored config diffs empty.
+    expect(jsonToText(d, { deterministic: true })).toBe(config);
+  });
+});

apps/server/src/common/helpers/client-version.spec.ts

@@ -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('');
+  });
+});

apps/server/src/common/helpers/client-version.ts

@@ -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 '';
+  }
+}

apps/server/src/common/helpers/index.ts

@@ -3,3 +3,4 @@ export * from './nanoid.utils';
 export * from './file.helper';
 export * from './constants';
 export * from './security-headers';
+export * from './client-version';

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

@@ -35,6 +35,7 @@ import {
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { UserThrottlerGuard } from '../../integrations/throttle/user-throttler.guard';
 import { AI_CHAT_THROTTLER } from '../../integrations/throttle/throttler-names';
@@ -43,6 +44,8 @@ import {
   AiChatRunHooks,
   AiChatService,
   AiChatStreamBody,
+  rowHasInlineParts,
+  hydrateAssistantParts,
 } from './ai-chat.service';
 import { AiChatRunService } from './ai-chat-run.service';
 import { AiTranscriptionService } from './ai-transcription.service';
@@ -129,8 +132,39 @@ export class AiChatController {
     // production. Only touched on the resumable-stream (flag-on) path.
     private readonly streamRegistry?: AiChatStreamRegistryService,
     private readonly environment?: EnvironmentService,
+    // #492: reconstruct a #492 mid-run record's parts from the steps table before
+    // returning rows to the client / export. OPTIONAL so positional controller
+    // specs compile unchanged; when absent, hydration is skipped (old-era rows
+    // already carry inline parts, so nothing to reconstruct).
+    private readonly aiChatRunStepRepo?: AiChatRunStepRepo,
   ) {}
 
+  /**
+   * Reconstruct parts for any assistant rows that don't carry them INLINE — a
+   * #492 mid-run record whose per-step parts live in `ai_chat_run_steps` (the
+   * append-persist backend). Every FINISHED row (old-era + #492) and every old-era
+   * streaming snapshot already has inline `metadata.parts`, so the common path
+   * fetches NOTHING and returns the rows untouched; only an actively-streaming
+   * new-style row triggers the batch step fetch. Consumers (seed/poll/export) read
+   * `metadata.parts` off the returned rows exactly as before — the era switch is
+   * invisible to them (reconstructRunParts contract).
+   */
+  private async withReconstructedParts(
+    rows: AiChatMessage[],
+    workspaceId: string,
+  ): Promise<AiChatMessage[]> {
+    if (!this.aiChatRunStepRepo) return rows;
+    const needy = rows.filter(
+      (r) => r.role === 'assistant' && !rowHasInlineParts(r),
+    );
+    if (needy.length === 0) return rows;
+    const stepsByMessage = await this.aiChatRunStepRepo.findByMessageIds(
+      needy.map((r) => r.id),
+      workspaceId,
+    );
+    return hydrateAssistantParts(rows, stepsByMessage);
+  }
+
   /** List the requesting user's chats in this workspace (paginated). */
   @HttpCode(HttpStatus.OK)
   @Post('chats')
@@ -184,11 +218,17 @@ export class AiChatController {
     @AuthWorkspace() workspace: Workspace,
   ) {
     await this.assertOwnedChat(dto.chatId, user, workspace);
-    return this.aiChatMessageRepo.findByChat(
+    const page = await this.aiChatMessageRepo.findByChat(
       dto.chatId,
       workspace.id,
       pagination,
     );
+    // #492: reconstruct parts for any active new-style row so the client seed sees
+    // `metadata.parts` unchanged (a no-op for the finished rows that fill a page).
+    return {
+      ...page,
+      items: await this.withReconstructedParts(page.items, workspace.id),
+    };
   }
 
   /**
@@ -225,7 +265,10 @@ export class AiChatController {
       workspace.id,
     );
     return {
-      rows,
+      // #492: the delta of an actively-streaming new-style row carries its parts
+      // reconstructed from the steps table, so the degraded poll shows persisted
+      // progress exactly as the pre-#492 full-row snapshot did.
+      rows: await this.withReconstructedParts(rows, workspace.id),
       cursor,
       run: run ? { id: run.id, status: run.status } : null,
     };
@@ -247,8 +290,10 @@ export class AiChatController {
     @AuthWorkspace() workspace: Workspace,
   ): Promise<{ markdown: string }> {
     const chat = await this.assertOwnedChat(dto.chatId, user, workspace);
-    const rows = await this.aiChatMessageRepo.findAllByChat(
-      dto.chatId,
+    const rows = await this.withReconstructedParts(
+      await this.aiChatMessageRepo.findAllByChat(dto.chatId, workspace.id),
+      // #492: an interrupted-but-still-active turn exports its persisted steps
+      // (reconstructed from the steps table) just like the pre-#492 full row did.
       workspace.id,
     );
     const markdown = buildChatMarkdown({
@@ -288,7 +333,13 @@ export class AiChatController {
           workspace.id,
         )
       : undefined;
-    return { run, message: message ?? null };
+    // #492: reconnect to an IN-FLIGHT run reconstructs the projection row's parts
+    // from the steps table (the row itself carries only the step marker mid-run);
+    // a finished run's row already has inline parts, so this is a no-op.
+    const [hydrated] = message
+      ? await this.withReconstructedParts([message], workspace.id)
+      : [undefined];
+    return { run, message: hydrated ?? null };
   }
 
   /**

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

@@ -370,10 +370,12 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
     );
   });
 
-  // #490 reactive branch: a provider CONTEXT-OVERFLOW 400 in onError is classified,
-  // records a distinguishable cause, and stamps metadata.replayOverflow so the NEXT
-  // turn's budgeter trims aggressively (the recovery that un-bricks the chat).
-  it('#490: a context-overflow 400 stamps replayOverflow on the finalized row', async () => {
+  // #490/#520 reactive branch: a provider CONTEXT-OVERFLOW 400 in onError is
+  // classified, records a distinguishable cause, and stamps the consecutive-overflow
+  // COUNTER (metadata.replayOverflowCount) so the NEXT turn's budgeter trims with
+  // escalating aggression (the recovery that un-bricks the chat). This is a fresh
+  // chat (empty history -> prior streak 0), so the first overflow stamps count 1.
+  it('#490/#520: a context-overflow 400 stamps replayOverflowCount=1 on the finalized row', async () => {
     jest
       .spyOn(Logger.prototype, 'error')
       .mockImplementation(() => undefined as never);
@@ -397,11 +399,14 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       metadata: Record<string, unknown>;
     };
     expect(patch.status).toBe('error');
-    expect(patch.metadata.replayOverflow).toBe(true);
+    // First overflow on a fresh chat -> k = prior(0) + 1 = 1.
+    expect(patch.metadata.replayOverflowCount).toBe(1);
+    // The legacy boolean is no longer written (the counter supersedes it).
+    expect('replayOverflow' in patch.metadata).toBe(false);
     expect(patch.metadata.error).toContain('контекстное окно');
   });
 
-  it('#490: a non-overflow error does NOT stamp replayOverflow', async () => {
+  it('#490/#520: a non-overflow error does NOT stamp the overflow counter', async () => {
     jest
       .spyOn(Logger.prototype, 'error')
       .mockImplementation(() => undefined as never);
@@ -412,6 +417,7 @@ describe('AiChatService.stream — abortSignal wiring (#184 F3)', () => {
       status: string;
       metadata: Record<string, unknown>;
     };
+    expect('replayOverflowCount' in patch.metadata).toBe(false);
     expect('replayOverflow' in patch.metadata).toBe(false);
   });
 });

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

@@ -30,13 +30,16 @@ import {
   STEP_LIMIT_NO_ANSWER_MARKER,
   OUTPUT_DEGENERATION_ERROR,
   lastAssistantContextTokens,
-  lastAssistantReplayOverflow,
+  lastAssistantReplayOverflowCount,
   seedActivatedTools,
 } from './ai-chat.service';
 import type { AiChatMessage, Workspace } from '@docmost/db/types/entity.types';
 import { buildSystemPrompt } from './ai-chat.prompt';
 import type { McpClientsService } from './external-mcp/mcp-clients.service';
-import { resolveEffectiveReplayThreshold } from './history-budget';
+import {
+  resolveEffectiveReplayThreshold,
+  REPLAY_MIN_FLOOR_TOKENS,
+} from './history-budget';
 
 /**
  * Unit tests for compactToolOutput: the pure helper that shrinks tool outputs
@@ -554,49 +557,129 @@ describe('seedActivatedTools', () => {
   });
 });
 
-describe('lastAssistantReplayOverflow', () => {
+describe('lastAssistantReplayOverflowCount', () => {
   const row = (
     role: string,
     metadata: Record<string, unknown> | null,
   ): AiChatMessage => ({ role, metadata }) as unknown as AiChatMessage;
 
-  it('is true only when the LAST assistant turn overflowed', () => {
+  it('reads the consecutive-overflow count from the LAST assistant turn', () => {
     expect(
-      lastAssistantReplayOverflow([
-        row('assistant', { replayOverflow: true }),
+      lastAssistantReplayOverflowCount([
+        row('assistant', { replayOverflowCount: 3 }),
         row('user', null),
       ]),
-    ).toBe(true);
-    // A recovered (later, non-overflow) assistant turn clears it.
+    ).toBe(3);
+    // A recovered (later, non-overflow) assistant turn resets it to 0 — the read
+    // stops at the most recent assistant row, which carries no count.
     expect(
-      lastAssistantReplayOverflow([
-        row('assistant', { replayOverflow: true }),
+      lastAssistantReplayOverflowCount([
+        row('assistant', { replayOverflowCount: 3 }),
         row('user', null),
         row('assistant', { contextTokens: 5 }),
       ]),
-    ).toBe(false);
-    expect(lastAssistantReplayOverflow([])).toBe(false);
+    ).toBe(0);
+    expect(lastAssistantReplayOverflowCount([])).toBe(0);
   });
 
-  // #490 reactive recovery: a prior turn stamped `replayOverflow` must make the
-  // NEXT turn's effective budget the AGGRESSIVE 0.5x cut — that harder trim is
-  // what un-bricks a chat that just 400'd on the context window. This exercises
-  // the exact wiring the service uses: read the stamp, then scale the threshold.
-  it('#490: a prior replayOverflow drives the next turn to the 0.5x aggressive budget', () => {
+  // BACK-COMPAT (#520): an in-flight row written by the pre-#520 boolean stamp
+  // (`replayOverflow: true`, no count) reads as k=1 — the old single 0.5× behavior —
+  // so a chat mid-recovery across the deploy does not regress.
+  it('#520 back-compat: a legacy boolean replayOverflow reads as k=1', () => {
+    expect(
+      lastAssistantReplayOverflowCount([
+        row('assistant', { replayOverflow: true }),
+        row('user', null),
+      ]),
+    ).toBe(1);
+    // A legacy row with the flag absent/false is k=0.
+    expect(
+      lastAssistantReplayOverflowCount([row('assistant', { contextTokens: 5 })]),
+    ).toBe(0);
+  });
+
+  // A corrupt/negative persisted count never yields a negative k.
+  it('clamps a corrupt negative count to 0', () => {
+    expect(
+      lastAssistantReplayOverflowCount([
+        row('assistant', { replayOverflowCount: -4 }),
+      ]),
+    ).toBe(0);
+  });
+
+  // #490/#520 reactive recovery: the prior consecutive-overflow count `k` drives
+  // the next turn's effective budget to an ESCALATING cut (0.5**k) — each further
+  // consecutive 400 tightens it, which is what un-bricks a chat that keeps
+  // overflowing. This exercises the exact wiring the service uses: read the count,
+  // then scale the threshold.
+  it('#490/#520: the prior count drives the next turn to the escalating aggressive budget', () => {
     const history = [
-      row('assistant', { replayOverflow: true }),
+      row('assistant', { replayOverflowCount: 1 }),
       row('user', null),
     ];
-    const priorOverflowed = lastAssistantReplayOverflow(history);
-    expect(priorOverflowed).toBe(true);
-    // Base budget 100k -> aggressive recovery halves it to 50k this turn.
-    expect(resolveEffectiveReplayThreshold(100_000, priorOverflowed)).toBe(50_000);
+    const k = lastAssistantReplayOverflowCount(history);
+    expect(k).toBe(1);
+    // Base budget 100k -> first-overflow recovery halves it to 50k this turn.
+    expect(resolveEffectiveReplayThreshold(100_000, k)).toBe(50_000);
+    // A second consecutive overflow (k=2) quarters it.
+    expect(resolveEffectiveReplayThreshold(100_000, 2)).toBe(25_000);
     // Odd base floors, not rounds.
-    expect(resolveEffectiveReplayThreshold(99_999, true)).toBe(49_999);
-    // No prior overflow -> the base budget is used verbatim (no aggressive cut).
-    expect(resolveEffectiveReplayThreshold(100_000, false)).toBe(100_000);
+    expect(resolveEffectiveReplayThreshold(99_999, 1)).toBe(49_999);
+    // No prior overflow (k=0) -> the base budget is used verbatim (no cut).
+    expect(resolveEffectiveReplayThreshold(100_000, 0)).toBe(100_000);
     // An explicit off-switch (null) is never overridden, even on recovery.
-    expect(resolveEffectiveReplayThreshold(null, true)).toBeNull();
+    expect(resolveEffectiveReplayThreshold(null, 3)).toBeNull();
+  });
+
+  // #520 escalation table + convergence: the cut deepens each consecutive overflow
+  // and is CLAMPED at the floor so it converges (un-bricks even against a small
+  // real window), instead of the old fixed single 0.5× that stuck at 50k forever.
+  it('#520: escalates and converges to the floor, un-bricking a small real window', () => {
+    const base = 100_000;
+    expect(resolveEffectiveReplayThreshold(base, 0)).toBe(base);
+    expect(resolveEffectiveReplayThreshold(base, 1)).toBe(50_000);
+    expect(resolveEffectiveReplayThreshold(base, 2)).toBe(25_000);
+    expect(resolveEffectiveReplayThreshold(base, 3)).toBe(12_500);
+
+    // Residual-brick regression (#520): with the flat-default base (100k) and a real
+    // model window of ~40k, the OLD fixed 0.5× stuck at 50k forever (> 40k -> 400s
+    // again, never recovers). The escalating cut drops BELOW 40k after enough
+    // consecutive overflows -> the history finally fits -> the chat un-bricks.
+    const realWindow = 40_000;
+    // k=1 (50k) still exceeds the window — the old behavior's terminal state.
+    expect(resolveEffectiveReplayThreshold(base, 1)).toBeGreaterThan(realWindow);
+    // But escalation converges under the window within a couple more turns.
+    const converged = [2, 3, 4, 5].some(
+      (k) => (resolveEffectiveReplayThreshold(base, k) as number) < realWindow,
+    );
+    expect(converged).toBe(true);
+
+    // Convergence is bounded BELOW by the floor: a large k never trims below it.
+    for (const k of [4, 8, 20, 100]) {
+      expect(resolveEffectiveReplayThreshold(base, k)).toBe(REPLAY_MIN_FLOOR_TOKENS);
+      expect(
+        resolveEffectiveReplayThreshold(base, k) as number,
+      ).toBeGreaterThanOrEqual(REPLAY_MIN_FLOOR_TOKENS);
+    }
+  });
+
+  // The floor never RAISES a legitimately small configured budget above itself —
+  // that would re-overflow the very window it was configured for. Under #520 Option B
+  // recovery MAY cut it BELOW itself (down to floor(0.5×base) = the old 0.5× cut).
+  it('#520: never inflates a small configured budget above itself (may cut below)', () => {
+    const small = 5_000; // below the floor
+    const floor = Math.min(REPLAY_MIN_FLOOR_TOKENS, Math.floor(small * 0.5)); // 2500
+    expect(resolveEffectiveReplayThreshold(small, 0)).toBe(small);
+    // Even under escalation the effective threshold never exceeds the base, and never
+    // drops below the absolute floor.
+    for (const k of [1, 2, 3, 10]) {
+      const t = resolveEffectiveReplayThreshold(small, k) as number;
+      expect(t).toBeLessThanOrEqual(small);
+      expect(t).toBeGreaterThanOrEqual(floor);
+    }
+    // Option B: on overflow it DOES cut below the configured budget (old floor==budget
+    // behavior would keep this at `small`).
+    expect(resolveEffectiveReplayThreshold(small, 1)).toBe(floor);
   });
 });
 
@@ -930,21 +1013,50 @@ describe('flushAssistant', () => {
     expect(flushed.metadata.error).toBe('boom');
   });
 
-  // #490 observability: the replay budgeter's decision is stamped on the turn.
-  it('records replayTrimmedToTokens + replayOverflow when provided', () => {
+  // #490/#520 observability: the replay budgeter's decision is stamped on the turn,
+  // now including the consecutive-overflow COUNTER (#520) the next turn escalates on.
+  it('records replayTrimmedToTokens + replayOverflowCount when provided', () => {
     const f = flushAssistant([], '', 'error', {
       error: 'ctx',
       replayTrimmedToTokens: 42_000,
-      replayOverflow: true,
+      replayOverflowCount: 2,
     });
     expect(f.metadata.replayTrimmedToTokens).toBe(42_000);
-    expect(f.metadata.replayOverflow).toBe(true);
+    expect(f.metadata.replayOverflowCount).toBe(2);
   });
 
   it('omits the replay metadata when not provided', () => {
     const f = flushAssistant([], '', 'completed', { finishReason: 'stop' });
     expect('replayTrimmedToTokens' in f.metadata).toBe(false);
-    expect('replayOverflow' in f.metadata).toBe(false);
+    expect('replayOverflowCount' in f.metadata).toBe(false);
+    expect('replayBelowConfiguredBudget' in f.metadata).toBe(false);
+  });
+
+  // #520 Option B observability: the turn is marked when recovery replayed BELOW the
+  // admin-configured budget, so the UI/telemetry can surface "config too large".
+  it('stamps replayBelowConfiguredBudget when recovery cut below the configured budget', () => {
+    const f = flushAssistant([], '', 'error', {
+      error: 'ctx',
+      replayOverflowCount: 2,
+      replayBelowConfiguredBudget: true,
+    });
+    // MUTATION SENTINEL: dropping the metadata stamp in flushAssistant reddens this.
+    expect(f.metadata.replayBelowConfiguredBudget).toBe(true);
+  });
+
+  it('omits replayBelowConfiguredBudget on a normal in-budget replay', () => {
+    // false/omitted must NOT leave the flag on the turn (only the below-budget case).
+    const off = flushAssistant([], '', 'completed', {
+      replayBelowConfiguredBudget: false,
+    });
+    expect('replayBelowConfiguredBudget' in off.metadata).toBe(false);
+  });
+
+  // A clean finalize (no overflow -> count 0/omitted) leaves NO counter, which the
+  // next turn reads as k=0 — the reset that ends a recovery streak.
+  it('omits replayOverflowCount for a zero/absent count (reset semantics)', () => {
+    const zero = flushAssistant([], '', 'completed', { replayOverflowCount: 0 });
+    expect('replayOverflowCount' in zero.metadata).toBe(false);
   });
 
   // #274 observability: the page-change diff the agent saw this turn is persisted

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

@@ -22,6 +22,7 @@ import { AiSettingsService } from '../../integrations/ai/ai-settings.service';
 import { describeProviderError } from '../../integrations/ai/ai-error.util';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
+import { AiChatRunStepRepo } from '@docmost/db/repos/ai-chat/ai-chat-run-step.repo';
 import { AiChatPageSnapshotRepo } from '@docmost/db/repos/ai-chat/ai-chat-page-snapshot.repo';
 import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
@@ -140,9 +141,10 @@ const OUTPUT_DEGENERATION_ERROR =
 
 // Prefix recorded on the assistant row when the provider rejected the turn for
 // CONTEXT OVERFLOW (#490): the replayed history exceeded the model's window. The
-// row is ALSO stamped `metadata.replayOverflow` so the NEXT turn's budgeter trims
-// aggressively (the reactive recovery — the overflowing turn had no usage signal
-// to trigger preventive trimming, so the classified 400 is what un-bricks it).
+// row is ALSO stamped `metadata.replayOverflowCount` (the consecutive-overflow
+// counter, #520) so the NEXT turn's budgeter trims with escalating aggression (the
+// reactive recovery — the overflowing turn had no usage signal to trigger
+// preventive trimming, so the classified 400 is what un-bricks it).
 export const CONTEXT_OVERFLOW_ERROR_PREFIX =
   'Диалог превысил контекстное окно модели; история будет агрессивно ' +
   'сокращена на следующем ходу.';
@@ -189,10 +191,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.
@@ -517,6 +520,12 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
     // constructions compile unchanged; Nest always injects the real singleton, so
     // reconcile sees the SAME in-memory active/zombie maps the runner mutates.
     private readonly aiChatRunService?: AiChatRunService,
+    // #492 append-persist: per-step INSERT into the lightweight steps table (the
+    // O(Σ steps) replacement for the O(n²) full-row `metadata.parts` rewrite).
+    // OPTIONAL so existing positional constructions (int-specs) compile unchanged;
+    // Nest injects the real singleton. When ABSENT the per-step path falls back to
+    // the pre-#492 full-row flush (no regression, only no WAL win).
+    private readonly aiChatRunStepRepo?: AiChatRunStepRepo,
   ) {}
 
   // #487: periodic reconcile timer (single-process phase 1). Started in
@@ -1113,8 +1122,34 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
         chatId,
         workspace.id,
       );
+      // #492: HYDRATE needy assistant rows from the steps table BEFORE the replay
+      // map. A #492 mid-run assistant row carries only a step marker
+      // (metadata.parts:[]); its real per-step parts live in `ai_chat_run_steps`.
+      // The graceful terminal callbacks (onFinish/onError/onAbort -> flushAssistant)
+      // assemble the full inline parts, so a normally-ended turn already has them.
+      // But a HARD crash mid-run (SIGKILL/OOM) fires NO terminal callback, so the
+      // row stays parts:[]; without this, rowToUiMessage falls back to an empty
+      // text part and the partial tool-calls/results/text — durable in the steps
+      // table — would DROP OUT of the model's replay context (regressing #183
+      // step-granular durability for the model consumer). Mirrors the controller's
+      // withReconstructedParts EXACTLY (same needy predicate + hydration helper).
+      // Guarded on the optional repo: absent (positional test builds) degrades to
+      // the current behavior rather than crashing.
+      let replayHistory = oldHistory;
+      if (this.aiChatRunStepRepo) {
+        const needy = oldHistory.filter(
+          (r) => r.role === 'assistant' && !rowHasInlineParts(r),
+        );
+        if (needy.length > 0) {
+          const stepsByMessage = await this.aiChatRunStepRepo.findByMessageIds(
+            needy.map((r) => r.id),
+            workspace.id,
+          );
+          replayHistory = hydrateAssistantParts(oldHistory, stepsByMessage);
+        }
+      }
       const uiMessages: Array<Omit<UIMessage, 'id'> & { id: string }> = [
-        ...oldHistory.map(rowToUiMessage),
+        ...replayHistory.map(rowToUiMessage),
         {
           id: 'pending-user',
           role: 'user',
@@ -1153,7 +1188,9 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       // hint — confirm it against the persisted history (the preceding assistant
       // turn must really be aborted/streaming) so a spoofed flag cannot inject the
       // interrupt note onto an ordinary turn. The partial output the model needs is
-      // already in `messages` (the aborted assistant row replays via findRecent).
+      // already in `messages`: a #492 mid-run row's per-step parts live only in the
+      // `ai_chat_run_steps` table and were hydrated into the replay history above,
+      // so the aborted assistant turn replays WITH its partial parts intact.
       // Append the new user turn (shape-only) so index -2 is the prior assistant.
       const interrupted = isInterruptResume(
         [...oldHistory, { role: 'user', status: null, metadata: null }],
@@ -1192,27 +1229,52 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       }
       // Last turn's provider-reported context size (authoritative when present).
       const priorContextTokens = lastAssistantContextTokens(oldHistory);
-      // Reactive recovery (#490): if the LAST turn was rejected for context
-      // overflow (stamped by onError), trim AGGRESSIVELY this turn — the
-      // overflowing turn produced no usage signal, so a normal-threshold trim may
-      // not shrink enough to fit. This is what un-bricks a chat that just 400'd.
-      const priorOverflowed = lastAssistantReplayOverflow(oldHistory);
+      // Reactive recovery (#490/#520): `k` = how many CONSECUTIVE preceding turns
+      // were rejected for context overflow (stamped by onError). Each consecutive
+      // overflow trims MORE aggressively (resolveEffectiveReplayThreshold scales the
+      // budget by 0.5**k, clamped at the floor) so recovery ESCALATES until the
+      // history fits — the overflowing turn produced no usage signal, so a single
+      // fixed cut may not shrink enough when the real model window is small. This is
+      // what un-bricks a chat that keeps 400'ing on the context window.
+      const priorOverflowCount = lastAssistantReplayOverflowCount(oldHistory);
       const effectiveThreshold = resolveEffectiveReplayThreshold(
         replayBudget.thresholdTokens,
-        priorOverflowed,
+        priorOverflowCount,
       );
-      if (priorOverflowed) {
-        this.logger.warn(
-          `AI chat (chat ${chatId}): previous turn hit context overflow; ` +
-            `applying aggressive replay budget (${effectiveThreshold} tokens).`,
-        );
+      // #520 Option B: recovery MAY cut the replay budget BELOW the admin-configured
+      // window when the provider keeps proving non-fit (the anti-brick invariant of
+      // the reactive branch beats a config that a 400 has disproved). Surface it so
+      // the admin sees their window is factually too large, and mark the turn so the
+      // UI/telemetry can show it. Only true when actually below (not on in-budget
+      // escalation edge cases); k>0 implies below for any budget >= 2 tokens.
+      const replayBelowConfiguredBudget =
+        replayBudget.thresholdTokens != null &&
+        effectiveThreshold != null &&
+        effectiveThreshold < replayBudget.thresholdTokens;
+      if (priorOverflowCount > 0) {
+        if (replayBelowConfiguredBudget) {
+          this.logger.warn(
+            `AI chat (chat ${chatId}): configured replay budget ` +
+              `(${replayBudget.thresholdTokens} tokens) does not fit the model — ` +
+              `replaying BELOW it at ${effectiveThreshold} tokens after ` +
+              `${priorOverflowCount} consecutive context overflow(s) ` +
+              `(escalation level ${priorOverflowCount}). Lower chatContextWindow ` +
+              `to match the model's real context window.`,
+          );
+        } else {
+          this.logger.warn(
+            `AI chat (chat ${chatId}): ${priorOverflowCount} consecutive context ` +
+              `overflow(s); applying escalated aggressive replay budget ` +
+              `(${effectiveThreshold} tokens).`,
+          );
+        }
       }
       const preTrim = trimHistoryForReplay(
         messages,
         effectiveThreshold,
         // A prior OVERFLOW means the provider count is stale/absent — force the
         // char-estimate path by ignoring priorContextTokens on recovery.
-        priorOverflowed ? undefined : priorContextTokens,
+        priorOverflowCount > 0 ? undefined : priorContextTokens,
       );
       messages = preTrim.messages;
       // Observability (#490): record the budgeter's decision on the turn so the UI
@@ -1410,10 +1472,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
@@ -1557,17 +1620,57 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
         // connection when finalize runs, so the SQL `WHERE status='streaming'`
         // (not this flag) is what prevents it clobbering the terminal row.
         if (finalized) return null;
-        // Build the flush ONCE so the returned count is EXACTLY the persisted
-        // `stepsPersisted` (both derive from capturedSteps.length at this instant).
-        const flushed = flushAssistant(capturedSteps, '', 'streaming', {
-          pageChanged,
-          partsCache,
-        });
-        const stepsPersisted = flushed.metadata.stepsPersisted as number;
+        // The count derives from capturedSteps.length at THIS instant, so the
+        // returned value is EXACTLY the persisted `stepsPersisted` the ring rotates
+        // on (whether we take the append-persist path or the legacy fallback).
+        const stepsPersisted = capturedSteps.length;
         try {
-          await this.aiChatMessageRepo.update(assistantId, workspace.id, flushed, {
-            onlyIfStreaming: true,
-          });
+          if (this.aiChatRunStepRepo) {
+            // #492 APPEND-PERSIST: write only THIS finished step's parts to the
+            // steps table (O(step) WAL), then bump the row's CHEAP step marker —
+            // NO growing `metadata.parts` blob (that O(n²) full-row rewrite is
+            // exactly what this removes). The full `metadata.parts` is assembled
+            // once at finalize; a mid-run resume seed is reconstructed from the
+            // step rows (reconstructRunParts). The INSERT is idempotent
+            // (ON CONFLICT DO NOTHING), so a re-fired step never doubles the parts.
+            const index = stepsPersisted - 1;
+            if (index >= 0) {
+              const stepParts = assistantParts(
+                [capturedSteps[index]],
+                '',
+                partsCache,
+              );
+              await this.aiChatRunStepRepo.insertStep(
+                assistantId,
+                workspace.id,
+                index,
+                stepParts,
+              );
+            }
+            // Marker UPDATE: advance stepsPersisted + keep the toolTrace era marker
+            // (bumps updatedAt so the delta poll observes the step, and carries the
+            // frontier a resuming client attaches from). Scoped onlyIfStreaming so a
+            // late marker never clobbers the terminal finalize.
+            await this.aiChatMessageRepo.update(
+              assistantId,
+              workspace.id,
+              { metadata: stepMarkerMetadata(stepsPersisted) },
+              { onlyIfStreaming: true },
+            );
+          } else {
+            // Legacy fallback (no steps table wired — positional test builds): the
+            // pre-#492 full-row flush, so parts still land inline on the row.
+            const flushed = flushAssistant(capturedSteps, '', 'streaming', {
+              pageChanged,
+              partsCache,
+            });
+            await this.aiChatMessageRepo.update(
+              assistantId,
+              workspace.id,
+              flushed,
+              { onlyIfStreaming: true },
+            );
+          }
           return stepsPersisted;
         } catch (err) {
           this.logger.warn(
@@ -1826,6 +1929,10 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 pageChanged,
                 partsCache,
                 replayTrimmedToTokens,
+                // #520 Option B: mark the turn when recovery replayed BELOW the
+                // configured budget (only when it actually did).
+                replayBelowConfiguredBudget:
+                  replayBelowConfiguredBudget || undefined,
               }),
             );
             // #184/#487: the RUN is finalized ALWAYS (never gated on the message).
@@ -1904,7 +2011,16 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
                 pageChanged,
                 partsCache,
                 replayTrimmedToTokens,
-                replayOverflow: overflow || undefined,
+                // #520: escalate the consecutive-overflow counter so the NEXT turn
+                // trims MORE aggressively (0.5**k). k grows by 1 each consecutive
+                // overflow; a clean finalize omits the field, resetting it to 0.
+                replayOverflowCount: overflow
+                  ? priorOverflowCount + 1
+                  : undefined,
+                // #520 Option B: mark the turn when THIS replay was already below the
+                // configured budget (only when it actually was).
+                replayBelowConfiguredBudget:
+                  replayBelowConfiguredBudget || undefined,
               }),
             );
             // #184: settle the RUN as failed, carrying the provider/transport cause.
@@ -2336,22 +2452,39 @@ export function seedActivatedTools(
 }
 
 /**
- * Whether the most recent assistant turn was rejected for CONTEXT OVERFLOW
- * (#490): its row carries `metadata.replayOverflow` (stamped by the stream's
- * onError). The next turn's budgeter reads this to trim aggressively — the
- * reactive recovery. Only the LAST assistant turn matters (an older overflow was
- * already recovered), so we stop at the first assistant row scanning backwards.
+ * How many CONSECUTIVE recent turns were rejected for CONTEXT OVERFLOW (#490/#520):
+ * `k`, read from the most recent assistant row's `metadata.replayOverflowCount`
+ * (stamped by the stream's onError, incremented each consecutive overflow and reset
+ * to 0 on any clean finalize). The next turn's budgeter feeds this to
+ * {@link resolveEffectiveReplayThreshold} to trim with ESCALATING aggression — the
+ * reactive recovery. Only the LAST assistant turn matters (its count already carries
+ * the consecutive streak; an older overflow followed by a clean turn was recovered),
+ * so we stop at the first assistant row scanning backwards.
+ *
+ * BACK-COMPAT: a row written by the pre-#520 boolean stamp (`replayOverflow: true`,
+ * no count) is read as k=1 — the old single 0.5× behavior — so in-flight chats do
+ * not regress across the deploy.
  */
-export function lastAssistantReplayOverflow(
+export function lastAssistantReplayOverflowCount(
   history: ReadonlyArray<AiChatMessage>,
-): boolean {
+): number {
   for (let i = history.length - 1; i >= 0; i--) {
     const row = history[i];
     if (row.role !== 'assistant') continue;
-    const meta = (row.metadata ?? {}) as { replayOverflow?: unknown };
-    return meta.replayOverflow === true;
+    const meta = (row.metadata ?? {}) as {
+      replayOverflowCount?: unknown;
+      replayOverflow?: unknown;
+    };
+    if (typeof meta.replayOverflowCount === 'number') {
+      // Guard against a corrupt/negative persisted value.
+      return meta.replayOverflowCount > 0
+        ? Math.floor(meta.replayOverflowCount)
+        : 0;
+    }
+    // Back-compat: legacy boolean stamp -> one overflow (0.5× cut).
+    return meta.replayOverflow === true ? 1 : 0;
   }
-  return false;
+  return 0;
 }
 
 /** The last message with role 'user' from a useChat payload, if any. */
@@ -2747,6 +2880,122 @@ export function rowToUiMessage(row: AiChatMessage): Omit<UIMessage, 'id'> & {
   return { id: row.id, role, parts: parts as UIMessage['parts'] };
 }
 
+/**
+ * Cheap step-marker metadata for the #492 per-step UPDATE. Advances
+ * `stepsPersisted` (the resume attach frontier) and keeps the `toolTraceVersion`
+ * era marker, WITHOUT the growing `parts` blob (those live in the steps table
+ * now; the full `metadata.parts` is assembled once at finalize by flushAssistant).
+ * `parts: []` is kept for shape stability — it reads as an empty inline-parts row,
+ * which is exactly the discriminator that routes reconstruction to the steps table.
+ */
+export function stepMarkerMetadata(
+  stepsPersisted: number,
+): Record<string, unknown> {
+  return { parts: [], toolTraceVersion: 2, stepsPersisted };
+}
+
+/**
+ * Whether an assistant row already carries its full UI parts INLINE on the row
+ * (`metadata.parts`). TRUE for every FINISHED row — old-era rows AND #492 rows,
+ * whose full parts are assembled once at finalize — and for old-era streaming
+ * snapshots (the pre-#492 per-step full-row flush). FALSE for a #492 MID-RUN
+ * record, whose per-step parts live in the `ai_chat_run_steps` table. This is the
+ * era discriminator the reconstruct seam branches on — no schema flag needed.
+ */
+export function rowHasInlineParts(row: { metadata?: unknown }): boolean {
+  const meta = (row.metadata ?? {}) as { parts?: unknown };
+  return Array.isArray(meta.parts) && meta.parts.length > 0;
+}
+
+/**
+ * Concatenate persisted per-step parts (in `stepIndex` order) into the turn's UI
+ * parts (#492). Reproduces EXACTLY what flushAssistant → assistantParts would have
+ * written to `metadata.parts` for those finished steps, since each step row stored
+ * `assistantParts([step])` at persist time.
+ */
+export function assembleStepParts(
+  stepRows: ReadonlyArray<{ stepIndex: number; parts: unknown }>,
+): UIMessage['parts'] {
+  const parts: Array<Record<string, unknown>> = [];
+  for (const step of [...stepRows].sort((a, b) => a.stepIndex - b.stepIndex)) {
+    if (Array.isArray(step.parts)) {
+      parts.push(...(step.parts as Array<Record<string, unknown>>));
+    }
+  }
+  return parts as UIMessage['parts'];
+}
+
+/**
+ * reconstructRunParts (#492) — the single backend-switch seam. Given an assistant
+ * ROW and its persisted step rows, return the turn's UI `parts` + the persisted
+ * step count, reading from the ROW when it already carries inline parts (old-era
+ * records AND every finished record) and from the STEPS TABLE otherwise (a #492
+ * mid-run record). The higher-level consumers (attach seed, delta poll, export)
+ * route their row→parts through this / {@link hydrateAssistantParts}, so old and
+ * new records reconstruct identically WITHOUT the consumers branching on the era.
+ */
+export function reconstructRunParts(
+  row: { metadata?: unknown; content?: string | null },
+  stepRows: ReadonlyArray<{ stepIndex: number; parts: unknown }>,
+): { parts: UIMessage['parts']; stepsPersisted: number } {
+  if (rowHasInlineParts(row)) {
+    const meta = row.metadata as {
+      parts: UIMessage['parts'];
+      stepsPersisted?: number;
+    };
+    return {
+      parts: meta.parts,
+      stepsPersisted:
+        typeof meta.stepsPersisted === 'number'
+          ? meta.stepsPersisted
+          : stepRows.length,
+    };
+  }
+  if (stepRows.length > 0) {
+    return {
+      parts: assembleStepParts(stepRows),
+      stepsPersisted: stepRows.length,
+    };
+  }
+  // No inline parts and no step rows: an old-era seed / empty streaming row. Fall
+  // back to a single text part from `content` (mirrors rowToUiMessage).
+  return {
+    parts: textPart(row.content ?? '') as UIMessage['parts'],
+    stepsPersisted: 0,
+  };
+}
+
+/**
+ * Fill each assistant row's `metadata.parts` from its step rows when the row does
+ * not already carry them inline (a #492 mid-run record), so a consumer that reads
+ * `metadata.parts` off the RAW row (the client seed/poll, the Markdown export)
+ * sees the reconstructed parts with NO change to itself. Rows that already have
+ * inline parts (old-era + finished) and non-assistant rows pass through untouched.
+ * Pure: returns new row objects, never mutates the inputs.
+ */
+export function hydrateAssistantParts<
+  T extends { id: string; role?: string; metadata?: unknown },
+>(
+  rows: ReadonlyArray<T>,
+  stepsByMessage: Map<
+    string,
+    ReadonlyArray<{ stepIndex: number; parts: unknown }>
+  >,
+): T[] {
+  return rows.map((row) => {
+    if (row.role !== 'assistant' || rowHasInlineParts(row)) return row;
+    const steps = stepsByMessage.get(row.id);
+    if (!steps || steps.length === 0) return row;
+    return {
+      ...row,
+      metadata: {
+        ...((row.metadata ?? {}) as Record<string, unknown>),
+        parts: assembleStepParts(steps),
+      },
+    };
+  });
+}
+
 /**
  * The persisted-row patch shape produced by {@link flushAssistant}. It is the
  * SAME shape the assistant repo insert/update consume (content + toolCalls +
@@ -2891,9 +3140,16 @@ export function flushAssistant(
     // the (estimated) token size it trimmed to — the UI can show "replay truncated
     // at N tokens". Omitted when nothing was trimmed.
     replayTrimmedToTokens?: number;
-    // #490 reactive branch: set when the provider rejected this turn for context
-    // overflow. Stamped into metadata so the NEXT turn's budgeter trims aggressively.
-    replayOverflow?: boolean;
+    // #490/#520 reactive branch: the consecutive context-overflow count for THIS
+    // turn (prior streak + 1) when the provider rejected it for context overflow.
+    // Stamped into metadata so the NEXT turn's budgeter trims with escalating
+    // aggression (0.5**k). Omitted (undefined) on a clean turn, which resets k to 0.
+    replayOverflowCount?: number;
+    // #520 Option B observability: true when recovery replayed this turn's history
+    // BELOW the admin-configured budget (the configured window did not fit and the
+    // anti-brick invariant cut past it). Omitted on a normal in-budget replay so the
+    // flag marks ONLY the "config is factually too large" case.
+    replayBelowConfiguredBudget?: boolean;
   },
 ): AssistantFlush {
   const finished = capturedSteps ?? [];
@@ -2946,7 +3202,10 @@ export function flushAssistant(
     metadata.maxContextTokens = extra.maxContextTokens;
   if (extra?.replayTrimmedToTokens)
     metadata.replayTrimmedToTokens = extra.replayTrimmedToTokens;
-  if (extra?.replayOverflow) metadata.replayOverflow = true;
+  if (extra?.replayOverflowCount && extra.replayOverflowCount > 0)
+    metadata.replayOverflowCount = extra.replayOverflowCount;
+  if (extra?.replayBelowConfiguredBudget)
+    metadata.replayBelowConfiguredBudget = true;
   if (extra?.error) metadata.error = extra.error;
   // Persist the page-change diff the agent saw this turn (#274 observability),
   // so history / the Markdown export can show what the user changed. Only when

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

@@ -1,6 +1,11 @@
 import { randomBytes } from 'crypto';
 import { Client } from 'pg';
-import { flushAssistant, serializeSteps } from './ai-chat.service';
+import {
+  flushAssistant,
+  serializeSteps,
+  lastAssistantReplayOverflowCount,
+} from './ai-chat.service';
+import type { AiChatMessage } from '@docmost/db/types/entity.types';
 
 /**
  * #490 write-volume regression — an OBSERVABLE-PROPERTY test on a LIVE Postgres,
@@ -207,3 +212,111 @@ describe('#490 write-volume on a live Postgres (pg_current_wal_lsn delta)', () =
     expect(v2).toBeLessThan(v1 * 0.75);
   }, 120_000);
 });
+
+/**
+ * #520 reactive-recovery COUNTER lifecycle on a LIVE Postgres — proves the
+ * consecutive-overflow count survives a real jsonb metadata round-trip (the persist
+ * path), not just an in-memory object. flushAssistant BUILDS the row metadata, we
+ * WRITE it to a jsonb column, READ it back, then reconstruct the assistant row and
+ * run lastAssistantReplayOverflowCount over it — exactly the read the next turn does.
+ *
+ * The lifecycle proven end-to-end through pg:
+ *   - consecutive overflows INCREMENT k (1 -> 2 -> 3);
+ *   - a CLEAN finalize omits the field, which the reader treats as a RESET to 0;
+ *   - a legacy boolean row (`replayOverflow: true`) reads back as k=1 (back-compat).
+ */
+describe('#520 overflow-counter lifecycle on a live Postgres (jsonb round-trip)', () => {
+  let client: Client | undefined;
+  let available = false;
+
+  beforeAll(async () => {
+    try {
+      client = new Client(CONN);
+      await client.connect();
+      await client.query('SELECT 1');
+      available = true;
+    } catch {
+      available = false;
+      client = undefined;
+    }
+  });
+
+  afterAll(async () => {
+    await client?.end().catch(() => undefined);
+  });
+
+  // Round-trip an arbitrary metadata object through a real jsonb column and read it
+  // back as the reconstructed assistant row the next turn would load.
+  async function roundTrip(
+    c: Client,
+    metadata: unknown,
+  ): Promise<AiChatMessage> {
+    await c.query('UPDATE _wal_counter SET metadata=$1 WHERE id=1', [
+      JSON.stringify(metadata),
+    ]);
+    const back = (await c.query('SELECT metadata FROM _wal_counter WHERE id=1'))
+      .rows[0].metadata as Record<string, unknown>;
+    return { role: 'assistant', metadata: back } as unknown as AiChatMessage;
+  }
+
+  it('increments across consecutive overflows, resets on a clean turn, and honors the legacy boolean', async () => {
+    if (!available || !client) {
+      console.warn('SKIP: gitmost-test-pg not reachable; skipping counter test.');
+      return;
+    }
+    const c = client;
+    await c.query('DROP TABLE IF EXISTS _wal_counter');
+    await c.query('CREATE TABLE _wal_counter(id int primary key, metadata jsonb)');
+    await c.query("INSERT INTO _wal_counter VALUES (1, '{}'::jsonb)");
+
+    // Turn 1 overflow: prior streak 0 -> stamp k=1 (as the service does: prior+1).
+    let prior = lastAssistantReplayOverflowCount([]); // fresh chat
+    expect(prior).toBe(0);
+    let row = await roundTrip(
+      c,
+      flushAssistant([], '', 'error', {
+        error: 'ctx',
+        replayOverflowCount: prior + 1,
+      }).metadata,
+    );
+    prior = lastAssistantReplayOverflowCount([row]);
+    expect(prior).toBe(1);
+
+    // Turn 2 overflow: prior 1 -> stamp k=2.
+    row = await roundTrip(
+      c,
+      flushAssistant([], '', 'error', {
+        error: 'ctx',
+        replayOverflowCount: prior + 1,
+      }).metadata,
+    );
+    prior = lastAssistantReplayOverflowCount([row]);
+    expect(prior).toBe(2);
+
+    // Turn 3 overflow: prior 2 -> stamp k=3.
+    row = await roundTrip(
+      c,
+      flushAssistant([], '', 'error', {
+        error: 'ctx',
+        replayOverflowCount: prior + 1,
+      }).metadata,
+    );
+    prior = lastAssistantReplayOverflowCount([row]);
+    expect(prior).toBe(3);
+
+    // Turn 4 CLEAN finalize: no overflow -> the field is omitted -> reset to 0.
+    row = await roundTrip(
+      c,
+      flushAssistant([], 'all good', 'completed', { finishReason: 'stop' })
+        .metadata,
+    );
+    expect('replayOverflowCount' in (row.metadata as object)).toBe(false);
+    expect(lastAssistantReplayOverflowCount([row])).toBe(0);
+
+    // Back-compat: a row persisted by the pre-#520 boolean stamp reads back as k=1.
+    row = await roundTrip(c, { replayOverflow: true });
+    expect(lastAssistantReplayOverflowCount([row])).toBe(1);
+
+    await c.query('DROP TABLE IF EXISTS _wal_counter');
+  }, 60_000);
+});

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

@@ -1,14 +1,146 @@
 import type { ModelMessage } from 'ai';
 import {
   resolveReplayBudget,
+  resolveEffectiveReplayThreshold,
   isContextOverflowError,
   estimateMessagesTokens,
   trimHistoryForReplay,
   REPLAY_BUDGET_DEFAULT_TOKENS,
+  REPLAY_BUDGET_WINDOW_FRACTION,
+  REPLAY_MIN_FLOOR_TOKENS,
   REPLAY_TRUNCATION_MARKER,
   REPLAY_TURN_COLLAPSED_MARKER,
 } from './history-budget';
 
+describe('resolveEffectiveReplayThreshold (#520 iterative escalation)', () => {
+  // The escalation table: each consecutive overflow (k) deepens the cut by 0.5×.
+  it('scales the base by 0.5**k, flooring (not rounding) fractional tokens', () => {
+    const base = 100_000;
+    expect(resolveEffectiveReplayThreshold(base, 0)).toBe(base); // k=0: unchanged
+    expect(resolveEffectiveReplayThreshold(base, 1)).toBe(50_000); // 0.5×
+    expect(resolveEffectiveReplayThreshold(base, 2)).toBe(25_000); // 0.25×
+    expect(resolveEffectiveReplayThreshold(base, 3)).toBe(12_500); // 0.125×
+    // Floors, not rounds.
+    expect(resolveEffectiveReplayThreshold(99_999, 1)).toBe(49_999);
+  });
+
+  it('passes a null base (trimming OFF) through unchanged for any k', () => {
+    for (const k of [0, 1, 2, 5, 100]) {
+      expect(resolveEffectiveReplayThreshold(null, k)).toBeNull();
+    }
+  });
+
+  // The crux of #520: convergence. A large k is clamped at REPLAY_MIN_FLOOR_TOKENS,
+  // so the escalation CONVERGES to a small-but-usable budget instead of trimming to
+  // zero — and, unlike the old fixed 0.5× that stuck at 50k, it drops far enough to
+  // fit a small real model window.
+  it('clamps a large k at the floor (converges, never below)', () => {
+    const base = 100_000;
+    for (const k of [4, 6, 10, 50, 200]) {
+      const t = resolveEffectiveReplayThreshold(base, k) as number;
+      expect(t).toBe(REPLAY_MIN_FLOOR_TOKENS);
+      expect(t).toBeGreaterThanOrEqual(REPLAY_MIN_FLOOR_TOKENS);
+    }
+  });
+
+  // Residual-brick regression (#520): flat-default base 100k, real window ~40k. The
+  // OLD fixed single 0.5× stuck at 50k > 40k forever (re-overflows every turn — the
+  // brick). The iterative cut drops BELOW 40k after a couple more consecutive
+  // overflows, so the history finally fits and the chat un-bricks.
+  it('un-bricks: escalation drops below a small real window the fixed 0.5× never could', () => {
+    const base = 100_000;
+    const realWindow = 40_000;
+    // The old terminal state: 0.5× = 50k, still above the window.
+    expect(resolveEffectiveReplayThreshold(base, 1)).toBeGreaterThan(realWindow);
+    // Escalation converges under the window.
+    const converged = [2, 3, 4, 5].some(
+      (k) => (resolveEffectiveReplayThreshold(base, k) as number) < realWindow,
+    );
+    expect(converged).toBe(true);
+    // MUTATION SENTINEL: reverting `** k` to `** 1` (fixed 0.5×) makes every k yield
+    // 50k, so `converged` above would be FALSE and this test reddens. Removing the
+    // floor reddens the clamp test instead.
+  });
+
+  // "Don't INFLATE above itself" is still an invariant: the floor never RAISES a
+  // legitimately small configured budget above itself (that would re-overflow the
+  // very window it was set for). Under #520 Option B the floor is min(FLOOR,
+  // floor(0.5×base)), so for a base BELOW the floor recovery MAY cut it further —
+  // down to floor(0.5×base), i.e. AT LEAST the old single 0.5× cut — but never above.
+  it('never inflates a small configured budget above itself (may cut below it, #520 Option B)', () => {
+    const small = 5_000; // below REPLAY_MIN_FLOOR_TOKENS
+    const floor = Math.min(REPLAY_MIN_FLOOR_TOKENS, Math.floor(small * 0.5)); // 2500
+    expect(resolveEffectiveReplayThreshold(small, 0)).toBe(small); // k=0 unchanged
+    for (const k of [1, 2, 3, 10]) {
+      const t = resolveEffectiveReplayThreshold(small, k) as number;
+      // Invariant: never RAISED above the configured budget.
+      expect(t).toBeLessThanOrEqual(small);
+      // Option B: never trimmed below the absolute floor (converges).
+      expect(t).toBeGreaterThanOrEqual(floor);
+    }
+    // The old single 0.5× cut is reached (and pinned) — recovery is never WORSE than
+    // before, and DOES cut below the configured budget on overflow (Option B). Under
+    // the old floor==budget behavior this would be `small` (5000), not `floor`.
+    expect(resolveEffectiveReplayThreshold(small, 1)).toBe(floor);
+  });
+
+  // #520 Option B: with a configured window (NOT the flat default), repeated overflow
+  // escalates the replay budget BELOW the configured budget, down to the absolute
+  // floor — the chat must not brick even when the configured window is too large for
+  // the model. A CLEAN turn (k back to 0) restores the full configured budget.
+  it('escalates below the configured budget down to the floor, and resets on a clean turn', () => {
+    // Configured context window 8000 -> budget = floor(0.7 × 8000) = 5600 (the code's
+    // window->budget ratio; compute it, do not hardcode).
+    const window = 8_000;
+    const budget = resolveReplayBudget(window).thresholdTokens as number;
+    expect(budget).toBe(Math.floor(REPLAY_BUDGET_WINDOW_FRACTION * window)); // 5600
+
+    // The absolute floor for this budget = min(FLOOR, floor(0.5 × budget)) = 2800
+    // (a "small window": 0.5×budget < REPLAY_MIN_FLOOR_TOKENS), which is BELOW the
+    // 5600 configured budget.
+    const floor = Math.min(
+      REPLAY_MIN_FLOOR_TOKENS,
+      Math.floor(budget * 0.5),
+    ); // 2800
+    expect(floor).toBe(2_800);
+    expect(floor).toBeLessThan(budget); // below the configured budget
+
+    // k=0 -> full configured budget (no overflow yet).
+    expect(resolveEffectiveReplayThreshold(budget, 0)).toBe(budget);
+    // k=1 -> cut BELOW the configured budget to the 0.5× floor (2800). This is the
+    // MUTATION SENTINEL: with the OLD floor==configured-budget behavior this would be
+    // max(2800, 5600) = 5600 (never below budget), so the assertion reddens.
+    expect(resolveEffectiveReplayThreshold(budget, 1)).toBe(floor);
+    expect(resolveEffectiveReplayThreshold(budget, 1)).toBeLessThan(budget);
+    // k>=2 stays at the floor (converges, never below it).
+    for (const k of [2, 3, 5, 20]) {
+      expect(resolveEffectiveReplayThreshold(budget, k)).toBe(floor);
+    }
+
+    // A CLEAN turn resets k to 0 -> the full configured budget is restored (recovery
+    // is not sticky; it only bites while the provider keeps proving non-fit).
+    expect(resolveEffectiveReplayThreshold(budget, 0)).toBe(budget);
+  });
+
+  // #520 Option B, LARGE window: a big configured budget escalates in DISTINCT steps
+  // below itself, converging to the fixed absolute floor REPLAY_MIN_FLOOR_TOKENS.
+  it('a large configured budget escalates below itself down to REPLAY_MIN_FLOOR_TOKENS', () => {
+    const budget = resolveReplayBudget(200_000).thresholdTokens as number; // 140000
+    // The floor for a large window is the fixed REPLAY_MIN_FLOOR_TOKENS (8k), well
+    // BELOW the configured budget.
+    expect(
+      Math.min(REPLAY_MIN_FLOOR_TOKENS, Math.floor(budget * 0.5)),
+    ).toBe(REPLAY_MIN_FLOOR_TOKENS);
+    const seq = [0, 1, 2, 3, 4, 5, 6].map(
+      (k) => resolveEffectiveReplayThreshold(budget, k) as number,
+    );
+    expect(seq).toEqual([140_000, 70_000, 35_000, 17_500, 8_750, 8_000, 8_000]);
+    // Every escalated step (k>=1) is below the configured budget; convergence floor.
+    for (const t of seq.slice(1)) expect(t).toBeLessThan(budget);
+    expect(seq[seq.length - 1]).toBe(REPLAY_MIN_FLOOR_TOKENS);
+  });
+});
+
 describe('resolveReplayBudget', () => {
   it('uses floor(0.7 x window) for a configured window (no cap)', () => {
     // 0.7 x 60k = 42k

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

@@ -22,10 +22,35 @@ export const REPLAY_BUDGET_DEFAULT_TOKENS = 100_000;
 /** Fraction of a configured context window used as the budget. */
 export const REPLAY_BUDGET_WINDOW_FRACTION = 0.7;
 /**
- * Fraction of the normal budget used for the REACTIVE re-trim after a provider
- * context-overflow 400 — the preventive estimate under-counted, so cut harder.
+ * Per-step fraction of the normal budget applied on the REACTIVE re-trim after a
+ * provider context-overflow 400 — the preventive estimate under-counted, so cut
+ * harder. This is now applied ITERATIVELY: with `k` consecutive overflow turns the
+ * budget is scaled by `fraction ** k` (k=1 -> 0.5×, k=2 -> 0.25×, …), so recovery
+ * ESCALATES turn over turn until the replayed history finally fits, instead of the
+ * old single fixed 0.5× cut that could never un-brick a chat whose real model
+ * window is smaller than 0.5 × the (unconfigured, flat-default) base budget (#520).
  */
 export const REPLAY_AGGRESSIVE_FRACTION = 0.5;
+/**
+ * Absolute lower bound (tokens) on the escalating reactive budget: the iterative
+ * cut is clamped here so it CONVERGES (a fixed floor, not an ever-shrinking value
+ * that would eventually trim everything). Rationale: below ~8k tokens a chat cannot
+ * carry meaningful recent context, and even a small real model window comfortably
+ * fits this much — keep-recent-turns still applies on top, so a handful of recent
+ * turns survive.
+ *
+ * #520 Option B: for a LARGE configured window this floor sits BELOW the configured
+ * replay budget, and recovery is allowed to escalate PAST the configured budget down
+ * to it — "the chat must not brick on overflow" is an INVARIANT of the reactive
+ * branch, and a configured window is a claim about model capacity, not a promise
+ * about replay size; once the provider proves non-fit with a 400, reality beats the
+ * config. This does NOT change the NORMAL path's upper bound (#510 Option A still
+ * respects the configured budget while it fits) — it is survival once non-fit is
+ * proven. For a SMALL configured window the effective floor is instead the old
+ * single 0.5× cut (never worse than before, and never RAISED above the budget); see
+ * {@link resolveEffectiveReplayThreshold}.
+ */
+export const REPLAY_MIN_FLOOR_TOKENS = 8_000;
 /**
  * Turns (a user message + its assistant/tool replies) kept FULL at the tail,
  * including the current one — never trimmed. Older turns are compacted first.
@@ -85,22 +110,48 @@ export function resolveReplayBudget(rawContextWindow: unknown): ReplayBudget {
 }
 
 /**
- * The effective replay threshold for THIS turn, given the base budget and whether
- * the PREVIOUS turn hit a context-overflow 400 (the reactive-recovery signal,
- * `metadata.replayOverflow`). On recovery the base budget is scaled down by
- * {@link REPLAY_AGGRESSIVE_FRACTION}: the overflowing turn produced no usage
- * signal, so the preventive estimate under-counted and a normal-threshold trim may
- * not shrink enough to fit — this harder cut is what un-bricks the chat.
+ * The effective replay threshold for THIS turn, given the base budget and `k` — the
+ * number of CONSECUTIVE preceding turns that hit a context-overflow 400 (the
+ * reactive-recovery signal `metadata.replayOverflowCount`, read from the last
+ * assistant row). On recovery the base budget is scaled down ITERATIVELY by
+ * {@link REPLAY_AGGRESSIVE_FRACTION} ** k and clamped at {@link REPLAY_MIN_FLOOR_TOKENS}:
+ *   - k=0 -> base unchanged (no overflow: nothing to recover from).
+ *   - k=1 -> floor(0.5 × base); k=2 -> floor(0.25 × base); … each further consecutive
+ *     overflow tightens the cut, so recovery ESCALATES until the history fits.
+ *   - the escalation is clamped at the floor so it CONVERGES — this is what un-bricks
+ *     a chat whose real model window is smaller than a single 0.5× cut of the base
+ *     (e.g. an unconfigured window: flat-default base 100k, real window <50k) (#520).
+ *
+ * The overflowing turn produced no usage signal, so the preventive estimate
+ * under-counted and a normal-threshold (or single fixed 0.5×) trim may not shrink
+ * enough to fit; the escalating cut is what recovers such a chat.
  *
  * A `null` base budget (trimming OFF) is passed through unchanged: an explicit
  * off-switch is never overridden by the recovery path.
+ *
+ * The absolute floor is `min(REPLAY_MIN_FLOOR_TOKENS, floor(0.5 × base))` (#520
+ * Option B):
+ *   - LARGE window (floor(0.5 × base) >= REPLAY_MIN_FLOOR_TOKENS) -> the fixed
+ *     REPLAY_MIN_FLOOR_TOKENS, which is BELOW the configured budget: escalation is
+ *     ALLOWED to cut past the configured budget down to this absolute minimum, so a
+ *     chat whose real model window is far smaller than the configured window still
+ *     un-bricks (the invariant beats a config reality disproved with a 400).
+ *   - SMALL window (floor(0.5 × base) < REPLAY_MIN_FLOOR_TOKENS) -> floor(0.5 ×
+ *     base), i.e. AT LEAST the old single 0.5× cut: recovery is never WORSE than the
+ *     pre-#520 behavior, and the floor is still never RAISED above the configured
+ *     budget itself (that would re-overflow the very window it was set for).
  */
 export function resolveEffectiveReplayThreshold(
   thresholdTokens: number | null,
-  priorOverflowed: boolean,
+  k: number,
 ): number | null {
-  if (!priorOverflowed || thresholdTokens == null) return thresholdTokens;
-  return Math.floor(thresholdTokens * REPLAY_AGGRESSIVE_FRACTION);
+  if (thresholdTokens == null || k <= 0) return thresholdTokens;
+  const scaled = Math.floor(thresholdTokens * REPLAY_AGGRESSIVE_FRACTION ** k);
+  const floor = Math.min(
+    REPLAY_MIN_FLOOR_TOKENS,
+    Math.floor(thresholdTokens * REPLAY_AGGRESSIVE_FRACTION),
+  );
+  return Math.max(scaled, floor);
 }
 
 /**

apps/server/src/core/api-key/api-key.controller.spec.ts

@@ -0,0 +1,193 @@
+import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import { ApiKeyController } from './api-key.controller';
+import {
+  WorkspaceCaslAction,
+  WorkspaceCaslSubject,
+} from '../casl/interfaces/workspace-ability.type';
+
+/**
+ * Authorization contract for the /api-keys management surface.
+ *
+ *  - A token cannot manage tokens (an api_key PRINCIPAL is 403 on every method)
+ *    — GitHub-PAT semantics closing post-revocation laundering.
+ *  - admin (CASL Manage on API) sees/revokes all workspace keys; a member only
+ *    their own.
+ *  - kill-switch OFF -> the surface 404s (looks like the feature does not exist).
+ */
+
+function makeController(over: any = {}) {
+  const apiKeyService = {
+    create: jest.fn().mockResolvedValue({
+      token: 'tok',
+      key: { id: 'k1', name: 'n', expiresAt: null, createdAt: new Date() },
+    }),
+    revoke: jest.fn().mockResolvedValue(undefined),
+    ...(over.apiKeyService ?? {}),
+  };
+  const apiKeyRepo = {
+    findAllInWorkspace: jest.fn().mockResolvedValue([]),
+    findByCreator: jest.fn().mockResolvedValue([]),
+    findById: jest.fn(),
+    ...(over.apiKeyRepo ?? {}),
+  };
+  const workspaceAbility = {
+    createForUser: jest.fn().mockReturnValue({
+      can: (_a: any, _s: any) => over.canManage ?? false,
+    }),
+    ...(over.workspaceAbility ?? {}),
+  };
+  const environmentService = {
+    isApiKeysEnabled: jest.fn().mockReturnValue(over.enabled ?? true),
+    ...(over.environmentService ?? {}),
+  };
+  const auditService = { log: jest.fn() };
+  const controller = new ApiKeyController(
+    apiKeyService as any,
+    apiKeyRepo as any,
+    workspaceAbility as any,
+    environmentService as any,
+    auditService as any,
+  );
+  return {
+    controller,
+    apiKeyService,
+    apiKeyRepo,
+    workspaceAbility,
+    environmentService,
+    auditService,
+  };
+}
+
+const user = { id: 'u-1', workspaceId: 'ws-1' } as any;
+const workspace = { id: 'ws-1' } as any;
+const reqAccess = () => ({ raw: {}, ip: '1.2.3.4', socket: {} }) as any;
+const reqApiKey = () =>
+  ({ raw: { authType: 'api_key', apiKeyId: 'k-self' }, ip: '1.2.3.4', socket: {} }) as any;
+
+describe('ApiKeyController — a token cannot manage tokens', () => {
+  it('403 on create for an api_key principal', async () => {
+    const { controller, apiKeyService } = makeController();
+    await expect(
+      controller.create({ name: 'x' } as any, user, reqApiKey()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(apiKeyService.create).not.toHaveBeenCalled();
+  });
+
+  it('403 on list for an api_key principal', async () => {
+    const { controller } = makeController();
+    await expect(
+      controller.list(user, workspace, reqApiKey()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+
+  it('403 on revoke for an api_key principal', async () => {
+    const { controller } = makeController();
+    await expect(
+      controller.revoke({ id: 'k1' } as any, user, workspace, reqApiKey()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('ApiKeyController — kill-switch OFF → 404', () => {
+  it('create/list/revoke all 404 when disabled', async () => {
+    const { controller } = makeController({ enabled: false });
+    await expect(
+      controller.create({ name: 'x' } as any, user, reqAccess()),
+    ).rejects.toBeInstanceOf(NotFoundException);
+    await expect(
+      controller.list(user, workspace, reqAccess()),
+    ).rejects.toBeInstanceOf(NotFoundException);
+    await expect(
+      controller.revoke({ id: 'k1' } as any, user, workspace, reqAccess()),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+});
+
+describe('ApiKeyController — list scoping', () => {
+  it('admin (Manage on API) lists ALL workspace keys', async () => {
+    const { controller, apiKeyRepo } = makeController({ canManage: true });
+    await controller.list(user, workspace, reqAccess());
+    expect(apiKeyRepo.findAllInWorkspace).toHaveBeenCalledWith('ws-1');
+    expect(apiKeyRepo.findByCreator).not.toHaveBeenCalled();
+  });
+
+  it('member lists ONLY their own keys', async () => {
+    const { controller, apiKeyRepo } = makeController({ canManage: false });
+    await controller.list(user, workspace, reqAccess());
+    expect(apiKeyRepo.findByCreator).toHaveBeenCalledWith('u-1', 'ws-1');
+    expect(apiKeyRepo.findAllInWorkspace).not.toHaveBeenCalled();
+  });
+});
+
+describe('ApiKeyController — revoke scoping', () => {
+  it("member cannot revoke another user's key (403)", async () => {
+    const { controller, apiKeyRepo, apiKeyService } = makeController({
+      canManage: false,
+    });
+    apiKeyRepo.findById.mockResolvedValue({
+      id: 'k1',
+      creatorId: 'someone-else',
+      workspaceId: 'ws-1',
+    });
+    await expect(
+      controller.revoke({ id: 'k1' } as any, user, workspace, reqAccess()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(apiKeyService.revoke).not.toHaveBeenCalled();
+  });
+
+  it('member CAN revoke their own key', async () => {
+    const { controller, apiKeyRepo, apiKeyService } = makeController({
+      canManage: false,
+    });
+    apiKeyRepo.findById.mockResolvedValue({
+      id: 'k1',
+      creatorId: 'u-1',
+      workspaceId: 'ws-1',
+    });
+    await controller.revoke({ id: 'k1' } as any, user, workspace, reqAccess());
+    expect(apiKeyService.revoke).toHaveBeenCalledWith('k1', 'ws-1');
+  });
+
+  it("admin CAN revoke another user's key", async () => {
+    const { controller, apiKeyRepo, apiKeyService } = makeController({
+      canManage: true,
+    });
+    apiKeyRepo.findById.mockResolvedValue({
+      id: 'k1',
+      creatorId: 'someone-else',
+      workspaceId: 'ws-1',
+    });
+    await controller.revoke({ id: 'k1' } as any, user, workspace, reqAccess());
+    expect(apiKeyService.revoke).toHaveBeenCalledWith('k1', 'ws-1');
+  });
+
+  it('404 when the key does not exist', async () => {
+    const { controller, apiKeyRepo } = makeController({ canManage: true });
+    apiKeyRepo.findById.mockResolvedValue(undefined);
+    await expect(
+      controller.revoke({ id: 'k1' } as any, user, workspace, reqAccess()),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+});
+
+describe('ApiKeyController — create emits audit + returns token once', () => {
+  it('logs API_KEY_CREATED and returns the token + computed expiry', async () => {
+    const { controller, auditService } = makeController();
+    const res = await controller.create(
+      { name: 'ci' } as any,
+      user,
+      reqAccess(),
+    );
+    expect(res.token).toBe('tok');
+    expect(res.apiKey).toMatchObject({ id: 'k1', name: 'n' });
+    expect(auditService.log).toHaveBeenCalledWith(
+      expect.objectContaining({ event: 'api_key.created' }),
+    );
+  });
+});
+
+// Sanity: the CASL subject used is the workspace API subject.
+it('uses WorkspaceCaslSubject.API with the Manage action', () => {
+  expect(WorkspaceCaslSubject.API).toBe('api_key');
+  expect(WorkspaceCaslAction.Manage).toBeDefined();
+});

apps/server/src/core/api-key/api-key.controller.ts

@@ -0,0 +1,201 @@
+import {
+  Body,
+  Controller,
+  ForbiddenException,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  Logger,
+  NotFoundException,
+  Post,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import { Throttle } from '@nestjs/throttler';
+import { FastifyRequest } from 'fastify';
+import { ApiKeyService } from './api-key.service';
+import { ApiKeyRepo } from '@docmost/db/repos/api-key/api-key.repo';
+import { CreateApiKeyDto } from './dto/create-api-key.dto';
+import { RevokeApiKeyDto } from './dto/revoke-api-key.dto';
+import { AuthUser } from '../../common/decorators/auth-user.decorator';
+import { AuthWorkspace } from '../../common/decorators/auth-workspace.decorator';
+import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
+import { User, Workspace } from '@docmost/db/types/entity.types';
+import WorkspaceAbilityFactory from '../casl/abilities/workspace-ability.factory';
+import {
+  WorkspaceCaslAction,
+  WorkspaceCaslSubject,
+} from '../casl/interfaces/workspace-ability.type';
+import { AuditEvent, AuditResource } from '../../common/events/audit-events';
+import {
+  AUDIT_SERVICE,
+  IAuditService,
+} from '../../integrations/audit/audit.service';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { UserThrottlerGuard } from '../../integrations/throttle/user-throttler.guard';
+import { AUTH_THROTTLER } from '../../integrations/throttle/throttler-names';
+
+@UseGuards(JwtAuthGuard)
+@Controller('api-keys')
+export class ApiKeyController {
+  private readonly logger = new Logger(ApiKeyController.name);
+
+  constructor(
+    private readonly apiKeyService: ApiKeyService,
+    private readonly apiKeyRepo: ApiKeyRepo,
+    private readonly workspaceAbility: WorkspaceAbilityFactory,
+    private readonly environmentService: EnvironmentService,
+    @Inject(AUDIT_SERVICE) private readonly auditService: IAuditService,
+  ) {}
+
+  // Kill-switch OFF: the issuance surface disappears entirely (404), not a 403 —
+  // it must look like the feature does not exist.
+  private assertEnabled(): void {
+    if (!this.environmentService.isApiKeysEnabled()) {
+      throw new NotFoundException();
+    }
+  }
+
+  // A token cannot manage tokens (GitHub-PAT semantics): an api-key principal is
+  // refused on the management surface, so a leaked key cannot mint a replacement
+  // or revoke the keys that would lock it out (closes post-revocation laundering).
+  private rejectApiKeyPrincipal(req: FastifyRequest): void {
+    if ((req.raw as { authType?: string }).authType === 'api_key') {
+      throw new ForbiddenException('API keys cannot manage API keys');
+    }
+  }
+
+  private clientIp(req: FastifyRequest): string {
+    return req.ip ?? req.socket?.remoteAddress ?? 'unknown';
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @UseGuards(JwtAuthGuard, UserThrottlerGuard)
+  @Throttle({ [AUTH_THROTTLER]: { limit: 10, ttl: 60_000 } })
+  @Post('create')
+  async create(
+    @Body() dto: CreateApiKeyDto,
+    @AuthUser() user: User,
+    @Req() req: FastifyRequest,
+  ) {
+    this.assertEnabled();
+    this.rejectApiKeyPrincipal(req);
+
+    // undefined -> service default (1 year); null -> unlimited; string -> Date.
+    const expiresAt =
+      dto.expiresAt === undefined
+        ? undefined
+        : dto.expiresAt === null
+          ? null
+          : new Date(dto.expiresAt);
+
+    const { token, key } = await this.apiKeyService.create(
+      user,
+      dto.name,
+      expiresAt,
+    );
+
+    this.auditService.log({
+      event: AuditEvent.API_KEY_CREATED,
+      resourceType: AuditResource.API_KEY,
+      resourceId: key.id,
+    });
+    // The durable trail lives in container logs (AUDIT_SERVICE is a Noop in this
+    // build). No token material — the JWT is only ever returned in the response.
+    this.logger.log(
+      `API key created: id=${key.id} name=${JSON.stringify(
+        key.name,
+      )} actor=${user.id} expiresAt=${
+        key.expiresAt ? new Date(key.expiresAt).toISOString() : 'never'
+      } ip=${this.clientIp(req)}`,
+    );
+
+    // Return the token ONCE (never retrievable again) and the computed expiry so
+    // the caller/UI can surface "expires <date>" (the year-default time-bomb
+    // early-warning).
+    return {
+      token,
+      apiKey: {
+        id: key.id,
+        name: key.name,
+        expiresAt: key.expiresAt,
+        createdAt: key.createdAt,
+      },
+    };
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('list')
+  async list(
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+    @Req() req: FastifyRequest,
+  ) {
+    this.assertEnabled();
+    this.rejectApiKeyPrincipal(req);
+
+    const ability = this.workspaceAbility.createForUser(user, workspace);
+    // Admin (CASL Manage on API): every key in the workspace, attributed to its
+    // creator (closes "a leaked key of a departed employee is invisible"). A
+    // member sees only their own.
+    const keys = ability.can(
+      WorkspaceCaslAction.Manage,
+      WorkspaceCaslSubject.API,
+    )
+      ? await this.apiKeyRepo.findAllInWorkspace(workspace.id)
+      : await this.apiKeyRepo.findByCreator(user.id, workspace.id);
+
+    return keys.map((k) => ({
+      id: k.id,
+      name: k.name,
+      expiresAt: k.expiresAt,
+      lastUsedAt: k.lastUsedAt,
+      createdAt: k.createdAt,
+      creator: k.creator,
+    }));
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('revoke')
+  async revoke(
+    @Body() dto: RevokeApiKeyDto,
+    @AuthUser() user: User,
+    @AuthWorkspace() workspace: Workspace,
+    @Req() req: FastifyRequest,
+  ) {
+    this.assertEnabled();
+    this.rejectApiKeyPrincipal(req);
+
+    const key = await this.apiKeyRepo.findById(dto.id, workspace.id);
+    // Uniform 404 for a missing/already-revoked key regardless of who asks — no
+    // existence oracle for keys the caller may not own.
+    if (!key) {
+      throw new NotFoundException();
+    }
+
+    const ability = this.workspaceAbility.createForUser(user, workspace);
+    const canManageAll = ability.can(
+      WorkspaceCaslAction.Manage,
+      WorkspaceCaslSubject.API,
+    );
+    // Admin may revoke any key in the workspace; a member only their own.
+    if (!canManageAll && key.creatorId !== user.id) {
+      throw new ForbiddenException();
+    }
+
+    await this.apiKeyService.revoke(key.id, workspace.id);
+
+    this.auditService.log({
+      event: AuditEvent.API_KEY_DELETED,
+      resourceType: AuditResource.API_KEY,
+      resourceId: key.id,
+    });
+    this.logger.log(
+      `API key revoked: id=${key.id} name=${JSON.stringify(
+        key.name,
+      )} actor=${user.id} ip=${this.clientIp(req)}`,
+    );
+
+    return { success: true };
+  }
+}

apps/server/src/core/api-key/api-key.module.ts

@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+import { ApiKeyService } from './api-key.service';
+import { ApiKeyController } from './api-key.controller';
+import { TokenModule } from '../auth/token.module';
+
+// Core (non-EE) API-key feature: issuance REST endpoints + the shared validator
+// consumed by jwt.strategy (REST) and McpService (the /mcp Bearer router).
+// DatabaseModule (global) provides ApiKeyRepo/UserRepo/WorkspaceRepo; CaslModule
+// (global) provides WorkspaceAbilityFactory; TokenModule provides TokenService
+// (the no-exp api-key signer). ApiKeyService is exported so AuthModule (for
+// jwt.strategy) and McpModule (for the /mcp router) can inject it directly,
+// replacing the absent EE `ee/api-key` dynamic require.
+@Module({
+  imports: [TokenModule],
+  controllers: [ApiKeyController],
+  providers: [ApiKeyService],
+  exports: [ApiKeyService],
+})
+export class ApiKeyModule {}

apps/server/src/core/api-key/api-key.service.spec.ts

@@ -0,0 +1,299 @@
+import { UnauthorizedException } from '@nestjs/common';
+import { ApiKeyService } from './api-key.service';
+import { JwtType } from '../auth/dto/jwt-payload';
+
+/**
+ * Security contract for ApiKeyService.validate — the single validator shared by
+ * jwt.strategy (REST) and the /mcp Bearer router.
+ *
+ * Invariants under test:
+ *  - Anti-enumeration: every DEFINITE deny (missing/revoked/expired row, disabled
+ *    user, workspace mismatch, kill-switch off) throws the SAME bare
+ *    UnauthorizedException — an agent cannot distinguish expired from revoked.
+ *  - deny-on-decision / 5xx-on-infra: an UNEXPECTED (infra) error PROPAGATES as
+ *    itself (→ 5xx), never masked as a 401.
+ *  - Expiry is read from the ROW, never a JWT exp claim.
+ *  - No validate cache (each call re-reads the row → immediate revocation).
+ */
+
+const APP_SECRET = 'secret';
+
+function makeDeps(over: Partial<Record<string, any>> = {}) {
+  const apiKeyRepo = {
+    findById: jest.fn(),
+    insert: jest.fn(),
+    softDelete: jest.fn(),
+    touchLastUsed: jest.fn().mockResolvedValue(undefined),
+    ...(over.apiKeyRepo ?? {}),
+  };
+  const userRepo = {
+    findById: jest.fn(),
+    ...(over.userRepo ?? {}),
+  };
+  const workspaceRepo = {
+    findById: jest.fn().mockResolvedValue({ id: 'ws-1' }),
+    ...(over.workspaceRepo ?? {}),
+  };
+  const tokenService = {
+    generateApiToken: jest.fn().mockResolvedValue('minted.jwt.token'),
+    ...(over.tokenService ?? {}),
+  };
+  const environmentService = {
+    isApiKeysEnabled: jest.fn().mockReturnValue(true),
+    getApiKeysEnabledRaw: jest.fn().mockReturnValue(undefined),
+    getAppSecret: jest.fn().mockReturnValue(APP_SECRET),
+    ...(over.environmentService ?? {}),
+  };
+  const service = new (ApiKeyService as unknown as new (...a: any[]) => ApiKeyService)(
+    apiKeyRepo,
+    userRepo,
+    workspaceRepo,
+    tokenService,
+    environmentService,
+  );
+  return { service, apiKeyRepo, userRepo, workspaceRepo, tokenService, environmentService };
+}
+
+const payload = (over: Record<string, any> = {}) => ({
+  sub: 'u-1',
+  workspaceId: 'ws-1',
+  apiKeyId: 'key-1',
+  type: JwtType.API_KEY,
+  ...over,
+});
+
+const activeRow = (over: Record<string, any> = {}) => ({
+  id: 'key-1',
+  name: 'k',
+  creatorId: 'u-1',
+  workspaceId: 'ws-1',
+  expiresAt: null,
+  lastUsedAt: null,
+  deletedAt: null,
+  ...over,
+});
+
+const activeUser = (over: Record<string, any> = {}) => ({
+  id: 'u-1',
+  workspaceId: 'ws-1',
+  deactivatedAt: null,
+  deletedAt: null,
+  isAgent: false,
+  ...over,
+});
+
+describe('ApiKeyService.validate', () => {
+  it('returns { user, workspace } for a valid active key', async () => {
+    const { service, apiKeyRepo, userRepo } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(activeRow());
+    userRepo.findById.mockResolvedValue(activeUser());
+
+    const res = await service.validate(payload() as any);
+
+    expect(res.user).toMatchObject({ id: 'u-1' });
+    expect(res.workspace).toMatchObject({ id: 'ws-1' });
+    // Loads isAgent so downstream provenance does not silently degrade.
+    expect(userRepo.findById).toHaveBeenCalledWith('u-1', 'ws-1', {
+      includeIsAgent: true,
+    });
+  });
+
+  // --- Anti-enumeration: every deny is the SAME bare 401 -------------------
+  const denyCases: Array<[string, (d: ReturnType<typeof makeDeps>) => void]> = [
+    [
+      'missing/orphaned row',
+      (d) => d.apiKeyRepo.findById.mockResolvedValue(undefined),
+    ],
+    [
+      'revoked (soft-deleted → findById returns undefined)',
+      (d) => d.apiKeyRepo.findById.mockResolvedValue(undefined),
+    ],
+    [
+      'expired (expires_at in the past)',
+      (d) => {
+        d.apiKeyRepo.findById.mockResolvedValue(
+          activeRow({ expiresAt: new Date(Date.now() - 1000) }),
+        );
+        d.userRepo.findById.mockResolvedValue(activeUser());
+      },
+    ],
+    [
+      'disabled user',
+      (d) => {
+        d.apiKeyRepo.findById.mockResolvedValue(activeRow());
+        d.userRepo.findById.mockResolvedValue(
+          activeUser({ deactivatedAt: new Date() }),
+        );
+      },
+    ],
+    [
+      'user not found',
+      (d) => {
+        d.apiKeyRepo.findById.mockResolvedValue(activeRow());
+        d.userRepo.findById.mockResolvedValue(undefined);
+      },
+    ],
+    [
+      'creator/sub mismatch',
+      (d) => {
+        d.apiKeyRepo.findById.mockResolvedValue(activeRow({ creatorId: 'other' }));
+        d.userRepo.findById.mockResolvedValue(activeUser());
+      },
+    ],
+    [
+      'workspace row missing',
+      (d) => {
+        d.apiKeyRepo.findById.mockResolvedValue(activeRow());
+        d.userRepo.findById.mockResolvedValue(activeUser());
+        d.workspaceRepo.findById.mockResolvedValue(undefined);
+      },
+    ],
+    [
+      'kill-switch OFF',
+      (d) => d.environmentService.isApiKeysEnabled.mockReturnValue(false),
+    ],
+    [
+      'malformed payload (missing apiKeyId)',
+      () => undefined,
+    ],
+  ];
+
+  it.each(denyCases)(
+    'throws a bare UnauthorizedException with NO message for: %s',
+    async (label, arrange) => {
+      const deps = makeDeps();
+      arrange(deps);
+      const p =
+        label === 'malformed payload (missing apiKeyId)'
+          ? (payload({ apiKeyId: undefined }) as any)
+          : (payload() as any);
+
+      const err = await deps.service.validate(p).catch((e) => e);
+      expect(err).toBeInstanceOf(UnauthorizedException);
+      // Anti-enumeration: identical, class-less message for every failure mode.
+      expect(err.message).toBe('Unauthorized');
+    },
+  );
+
+  it('kill-switch OFF denies BEFORE any DB read', async () => {
+    const { service, apiKeyRepo, environmentService } = makeDeps();
+    environmentService.isApiKeysEnabled.mockReturnValue(false);
+
+    await expect(service.validate(payload() as any)).rejects.toBeInstanceOf(
+      UnauthorizedException,
+    );
+    expect(apiKeyRepo.findById).not.toHaveBeenCalled();
+  });
+
+  // --- Infra error propagates (5xx), NOT masked as 401 ---------------------
+  it('PROPAGATES an infra (DB) error instead of masking it as 401', async () => {
+    const { service, apiKeyRepo } = makeDeps();
+    const boom = new Error('connection terminated');
+    apiKeyRepo.findById.mockRejectedValue(boom);
+
+    await expect(service.validate(payload() as any)).rejects.toBe(boom);
+  });
+
+  // --- No cache: revocation is immediate on the next call ------------------
+  it('re-reads the row on every call (no validate cache → immediate revocation)', async () => {
+    const { service, apiKeyRepo, userRepo } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(activeRow());
+    userRepo.findById.mockResolvedValue(activeUser());
+    await service.validate(payload() as any);
+
+    // Now the key is revoked (row invisible) — the very next call denies.
+    apiKeyRepo.findById.mockResolvedValue(undefined);
+    await expect(service.validate(payload() as any)).rejects.toBeInstanceOf(
+      UnauthorizedException,
+    );
+    expect(apiKeyRepo.findById).toHaveBeenCalledTimes(2);
+  });
+
+  // --- last_used_at is throttled + fire-and-forget -------------------------
+  it('touches last_used_at when stale and skips when fresh', async () => {
+    const { service, apiKeyRepo, userRepo } = makeDeps();
+    userRepo.findById.mockResolvedValue(activeUser());
+
+    // Stale (never used) -> touch.
+    apiKeyRepo.findById.mockResolvedValue(activeRow({ lastUsedAt: null }));
+    await service.validate(payload() as any);
+    expect(apiKeyRepo.touchLastUsed).toHaveBeenCalledTimes(1);
+
+    // Fresh (used 1 minute ago) -> skip.
+    apiKeyRepo.touchLastUsed.mockClear();
+    apiKeyRepo.findById.mockResolvedValue(
+      activeRow({ lastUsedAt: new Date(Date.now() - 60_000) }),
+    );
+    await service.validate(payload() as any);
+    expect(apiKeyRepo.touchLastUsed).not.toHaveBeenCalled();
+  });
+
+  it('a failing last_used_at touch never fails the request', async () => {
+    const { service, apiKeyRepo, userRepo } = makeDeps();
+    apiKeyRepo.findById.mockResolvedValue(activeRow({ lastUsedAt: null }));
+    userRepo.findById.mockResolvedValue(activeUser());
+    apiKeyRepo.touchLastUsed.mockRejectedValue(new Error('write failed'));
+
+    await expect(service.validate(payload() as any)).resolves.toMatchObject({
+      user: { id: 'u-1' },
+    });
+  });
+});
+
+describe('ApiKeyService.create (mint-then-insert, no exp)', () => {
+  it('mints the JWT BEFORE inserting the row and returns the token once', async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    const order: string[] = [];
+    tokenService.generateApiToken.mockImplementation(async () => {
+      order.push('mint');
+      return 'tok';
+    });
+    apiKeyRepo.insert.mockImplementation(async (row: any) => {
+      order.push('insert');
+      return { ...row, createdAt: new Date() };
+    });
+
+    const user = { id: 'u-1', workspaceId: 'ws-1' } as any;
+    const res = await service.create(user, 'my key');
+
+    expect(order).toEqual(['mint', 'insert']);
+    expect(res.token).toBe('tok');
+    // The id is generated before minting and reused for the row.
+    const mintArg = tokenService.generateApiToken.mock.calls[0][0];
+    const insertArg = apiKeyRepo.insert.mock.calls[0][0];
+    expect(mintArg.apiKeyId).toBe(insertArg.id);
+  });
+
+  it('applies the 1-year default when expiresAt is undefined', async () => {
+    const { service, apiKeyRepo } = makeDeps();
+    apiKeyRepo.insert.mockImplementation(async (row: any) => row);
+    const user = { id: 'u-1', workspaceId: 'ws-1' } as any;
+
+    await service.create(user, 'k');
+
+    const insertArg = apiKeyRepo.insert.mock.calls[0][0];
+    const days =
+      (insertArg.expiresAt.getTime() - Date.now()) / (24 * 60 * 60 * 1000);
+    expect(days).toBeGreaterThan(364);
+    expect(days).toBeLessThan(367);
+  });
+
+  it('honors an explicit null (unlimited)', async () => {
+    const { service, apiKeyRepo } = makeDeps();
+    apiKeyRepo.insert.mockImplementation(async (row: any) => row);
+    const user = { id: 'u-1', workspaceId: 'ws-1' } as any;
+
+    await service.create(user, 'k', null);
+
+    expect(apiKeyRepo.insert.mock.calls[0][0].expiresAt).toBeNull();
+  });
+
+  it('does NOT insert a row when minting fails (mint-then-insert → inert)', async () => {
+    const { service, apiKeyRepo, tokenService } = makeDeps();
+    tokenService.generateApiToken.mockRejectedValue(new Error('mint failed'));
+    const user = { id: 'u-1', workspaceId: 'ws-1' } as any;
+
+    await expect(service.create(user, 'k')).rejects.toThrow('mint failed');
+    expect(apiKeyRepo.insert).not.toHaveBeenCalled();
+  });
+});

apps/server/src/core/api-key/api-key.service.ts

@@ -0,0 +1,191 @@
+import {
+  Injectable,
+  Logger,
+  OnModuleInit,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { v7 as uuid7 } from 'uuid';
+import { ApiKeyRepo } from '@docmost/db/repos/api-key/api-key.repo';
+import { UserRepo } from '@docmost/db/repos/user/user.repo';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { TokenService } from '../auth/services/token.service';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
+import { JwtApiKeyPayload } from '../auth/dto/jwt-payload';
+import { ApiKey, User, Workspace } from '@docmost/db/types/entity.types';
+import { isUserDisabled } from '../../common/helpers';
+
+// Default lifetime for a new key when the caller does not specify one: 1 year.
+// The owner runs a homelab where agents live for years; forcing rotation is
+// operational pain, so an explicit `null` (unlimited) is also allowed.
+const DEFAULT_LIFETIME_MS = 365 * 24 * 60 * 60 * 1000;
+
+// last_used_at is a best-effort forensics stamp, not an access record; we only
+// refresh it when it is older than this to avoid a write on every request. The
+// 1h resolution is a deliberate constant (forensics granularity, not accounting).
+const LAST_USED_THROTTLE_MS = 60 * 60 * 1000;
+
+/**
+ * Core API-key lifecycle service. Owns minting (create), the single validator
+ * shared by BOTH the REST jwt.strategy path and the /mcp Bearer path (validate),
+ * and revocation (revoke). The `api_keys` ROW is the sole source of truth for a
+ * key's lifetime and revocation — never the JWT, which carries no `exp` claim.
+ */
+@Injectable()
+export class ApiKeyService implements OnModuleInit {
+  private readonly logger = new Logger(ApiKeyService.name);
+
+  constructor(
+    private readonly apiKeyRepo: ApiKeyRepo,
+    private readonly userRepo: UserRepo,
+    private readonly workspaceRepo: WorkspaceRepo,
+    private readonly tokenService: TokenService,
+    private readonly environmentService: EnvironmentService,
+  ) {}
+
+  onModuleInit() {
+    // Boot log so the kill-switch state after each deploy is verifiable in logs.
+    const enabled = this.environmentService.isApiKeysEnabled();
+    const raw = this.environmentService.getApiKeysEnabledRaw();
+    this.logger.log(
+      `API keys: ${enabled ? 'ENABLED' : 'DISABLED'} (API_KEYS_ENABLED=${
+        raw ?? 'unset'
+      })`,
+    );
+  }
+
+  /**
+   * Mint a new key for `user`. mint-then-insert ordering (R1):
+   *   1. generate the id first — it must be in the JWT payload before the row.
+   *   2. mint the JWT (no `exp` claim). A mint failure aborts before any row is
+   *      written (inert), so a half-created key cannot exist.
+   *   3. insert the row last. A lost response leaves an orphaned row that is
+   *      visible in `list` and self-heals (the user revokes it).
+   * The token is returned ONCE and never stored — the JWT is self-contained, so
+   * no token material lives in the table.
+   *
+   * `expiresAt`: `undefined` -> default 1 year; `null` -> unlimited (explicit);
+   * a Date -> that instant (a past date is rejected at the DTO layer).
+   */
+  async create(
+    user: User,
+    name: string,
+    expiresAt?: Date | null,
+  ): Promise<{ token: string; key: ApiKey }> {
+    const resolvedExpiresAt =
+      expiresAt === undefined
+        ? new Date(Date.now() + DEFAULT_LIFETIME_MS)
+        : expiresAt;
+
+    const apiKeyId = uuid7();
+
+    const token = await this.tokenService.generateApiToken({
+      apiKeyId,
+      user,
+      workspaceId: user.workspaceId,
+    });
+
+    const key = await this.apiKeyRepo.insert({
+      id: apiKeyId,
+      name,
+      creatorId: user.id,
+      workspaceId: user.workspaceId,
+      expiresAt: resolvedExpiresAt,
+    });
+
+    return { token, key };
+  }
+
+  /**
+   * The single validator for an api-key principal, shared by jwt.strategy and the
+   * /mcp Bearer router. Returns `{ user, workspace }` (the same shape the access
+   * path returns) so the AuthUser/AuthWorkspace decorators and MCP identity work
+   * unchanged.
+   *
+   * Failure semantics (R4, anti-enumeration): a DEFINITE negative fact — feature
+   * disabled, missing/revoked/expired row, workspace mismatch, disabled user —
+   * throws a bare `UnauthorizedException` (a single generic 401 for every case;
+   * an agent cannot distinguish expired from revoked, and its reaction is
+   * identical). An UNEXPECTED (infra) error is NOT caught here: it propagates so
+   * the surface returns 5xx, never a masked 401 (deny-on-decision / 5xx-on-infra).
+   * There is NO validate cache: it is 2–3 PK lookups (~1ms), two orders of
+   * magnitude cheaper than the bcrypt it replaces; a cache would only add a
+   * Date-serialization trap and a revocation lag. Revocation is immediate.
+   */
+  async validate(
+    payload: JwtApiKeyPayload,
+  ): Promise<{ user: User; workspace: Workspace }> {
+    // Kill-switch OFF: deny unconditionally (same generic 401). Note the
+    // endpoints additionally 404 at the controller; here we deny the token.
+    if (!this.environmentService.isApiKeysEnabled()) {
+      throw new UnauthorizedException();
+    }
+
+    if (!payload?.apiKeyId || !payload?.sub || !payload?.workspaceId) {
+      throw new UnauthorizedException();
+    }
+
+    const row = await this.apiKeyRepo.findById(
+      payload.apiKeyId,
+      payload.workspaceId,
+    );
+    // Absent row = revoked (soft-deleted, invisible to findById), orphaned
+    // (creator/workspace cascade-deleted), or never existed. All terminal deny.
+    if (!row) {
+      throw new UnauthorizedException();
+    }
+
+    // Expiry is read from the ROW, never an `exp` JWT claim.
+    if (row.expiresAt && row.expiresAt.getTime() <= Date.now()) {
+      throw new UnauthorizedException();
+    }
+
+    const user = await this.userRepo.findById(
+      payload.sub,
+      payload.workspaceId,
+      { includeIsAgent: true },
+    );
+    if (!user || isUserDisabled(user)) {
+      throw new UnauthorizedException();
+    }
+
+    // The key acts only as its creator (defence in depth against a token whose
+    // signed `sub` ever drifted from the row's owner).
+    if (row.creatorId !== user.id) {
+      throw new UnauthorizedException();
+    }
+
+    const workspace = await this.workspaceRepo.findById(payload.workspaceId);
+    if (!workspace) {
+      throw new UnauthorizedException();
+    }
+
+    // Best-effort, throttled, fire-and-forget forensics stamp AFTER all checks.
+    this.touchLastUsed(row);
+
+    return { user, workspace };
+  }
+
+  /**
+   * Revoke (soft-delete) a key. Authorization/ownership is decided by the caller
+   * (the controller, via CASL); this only performs the terminal write. Idempotent:
+   * a second revoke is a no-op (the row is already invisible).
+   */
+  async revoke(id: string, workspaceId: string): Promise<void> {
+    await this.apiKeyRepo.softDelete(id, workspaceId);
+  }
+
+  // Throttled best-effort last_used_at bump: skip if it was touched within the
+  // window; otherwise fire-and-forget so a stamp write never fails or slows the
+  // request (mirrors SessionActivityService.trackActivity).
+  private touchLastUsed(row: ApiKey): void {
+    const last = row.lastUsedAt ? new Date(row.lastUsedAt).getTime() : 0;
+    if (Date.now() - last < LAST_USED_THROTTLE_MS) return;
+    void this.apiKeyRepo.touchLastUsed(row.id).catch((err) => {
+      this.logger.warn(
+        `Failed to update api_key last_used_at for ${row.id}: ${
+          (err as Error)?.message ?? err
+        }`,
+      );
+    });
+  }
+}

apps/server/src/core/api-key/dto/create-api-key.dto.ts

@@ -0,0 +1,51 @@
+import {
+  IsDateString,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  MaxLength,
+  registerDecorator,
+  ValidationOptions,
+} from 'class-validator';
+
+/**
+ * `expiresAt` must be strictly in the future. Skips validation for `null`
+ * (explicit "unlimited") and `undefined` (server applies the 1-year default),
+ * so only an actually-supplied date is range-checked. Rejecting a PAST date at
+ * the DTO layer means a caller cannot mint an already-dead key.
+ */
+function IsFutureDateString(options?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      name: 'isFutureDateString',
+      target: object.constructor,
+      propertyName,
+      options: {
+        message: 'expiresAt must be a date in the future',
+        ...options,
+      },
+      validator: {
+        validate(value: unknown) {
+          if (value === null || value === undefined) return true;
+          if (typeof value !== 'string') return false;
+          const t = Date.parse(value);
+          return !Number.isNaN(t) && t > Date.now();
+        },
+      },
+    });
+  };
+}
+
+export class CreateApiKeyDto {
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  name: string;
+
+  // undefined -> default 1 year (applied server-side); null -> unlimited
+  // (explicit); an ISO date string -> that instant, which must be in the future.
+  @IsOptional()
+  @IsDateString()
+  @IsFutureDateString()
+  expiresAt?: string | null;
+}

apps/server/src/core/api-key/dto/revoke-api-key.dto.ts

@@ -0,0 +1,6 @@
+import { IsUUID } from 'class-validator';
+
+export class RevokeApiKeyDto {
+  @IsUUID()
+  id: string;
+}

apps/server/src/core/auth/auth.controller.spec.ts

@@ -20,3 +20,71 @@ describe('AuthController', () => {
     expect(controller).toBeDefined();
   });
 });
+
+// The collab-token handler is the ARM-SEAM of the #501 anti-laundering defense:
+// it derives the api-key origin args ({ apiKeyId }) from the SIGNED-derived
+// `req.raw` fields (stamped by jwt.strategy) and threads them into the collab
+// token mint, forcing principal='api_key' so a later key revoke rejects NEW
+// collab connections. A regression here (reading `body`, dropping `apiKeyId`,
+// or inverting the ternary) would silently mint api-key requests as
+// principal='session' and reopen the laundering hole with a green suite. These
+// tests pin the EXACT args the controller passes to authService.getCollabToken.
+describe('AuthController.collabToken arms the api-key origin (#501)', () => {
+  let controller: AuthController;
+  let getCollabToken: jest.Mock;
+
+  const user = { id: 'u-1', workspaceId: 'ws-1' } as any;
+  const workspace = { id: 'ws-1' } as any;
+
+  beforeEach(() => {
+    getCollabToken = jest.fn().mockResolvedValue({ token: 'ct' });
+    controller = new AuthController(
+      { getCollabToken } as any, // authService
+      {} as any, // sessionService
+      {} as any, // environmentService
+      {} as any, // moduleRef
+      {} as any, // auditService
+    );
+  });
+
+  it('threads { apiKeyId } when req.raw marks an api_key principal (ARMED)', async () => {
+    const req = { raw: { authType: 'api_key', apiKeyId: 'k-1' } } as any;
+
+    await controller.collabToken(user, workspace, req);
+
+    expect(getCollabToken).toHaveBeenCalledTimes(1);
+    expect(getCollabToken).toHaveBeenCalledWith(user, 'ws-1', {
+      apiKeyId: 'k-1',
+    });
+  });
+
+  it('passes undefined for a normal session request (NOT armed)', async () => {
+    const req = { raw: {} } as any;
+
+    await controller.collabToken(user, workspace, req);
+
+    expect(getCollabToken).toHaveBeenCalledTimes(1);
+    expect(getCollabToken).toHaveBeenCalledWith(user, 'ws-1', undefined);
+  });
+
+  it('does NOT arm when api_key authType lacks an apiKeyId', async () => {
+    const req = { raw: { authType: 'api_key' } } as any;
+
+    await controller.collabToken(user, workspace, req);
+
+    expect(getCollabToken).toHaveBeenCalledWith(user, 'ws-1', undefined);
+  });
+
+  it('reads the SIGNED req.raw, never a spoofable client body', async () => {
+    // A client-supplied body claiming api_key must be ignored: only the
+    // jwt.strategy-stamped req.raw can arm the api-key origin.
+    const req = {
+      raw: {},
+      body: { authType: 'api_key', apiKeyId: 'attacker' },
+    } as any;
+
+    await controller.collabToken(user, workspace, req);
+
+    expect(getCollabToken).toHaveBeenCalledWith(user, 'ws-1', undefined);
+  });
+});

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

@@ -207,8 +207,20 @@ export class AuthController {
   async collabToken(
     @AuthUser() user: User,
     @AuthWorkspace() workspace: Workspace,
+    @Req() req: FastifyRequest,
   ) {
-    return this.authService.getCollabToken(user, workspace.id);
+    // Thread the api-key origin (#501): when the requester authenticated with an
+    // api key (jwt.strategy stamped req.raw.authType/apiKeyId), the minted collab
+    // token carries principal='api_key' + apiKeyId so a later revoke of the key
+    // rejects NEW collab connections. A normal session request mints a
+    // principal='session' token. Reading the SIGNED-derived req.raw fields (never
+    // a client body) keeps it unspoofable.
+    const raw = req.raw as { authType?: string; apiKeyId?: string };
+    const apiKey =
+      raw.authType === 'api_key' && raw.apiKeyId
+        ? { apiKeyId: raw.apiKeyId }
+        : undefined;
+    return this.authService.getCollabToken(user, workspace.id, apiKey);
   }
 
   @SkipThrottle({ [AUTH_THROTTLER]: true })

apps/server/src/core/auth/auth.module.ts

@@ -5,9 +5,13 @@ import { JwtStrategy } from './strategies/jwt.strategy';
 import { WorkspaceModule } from '../workspace/workspace.module';
 import { SignupService } from './services/signup.service';
 import { TokenModule } from './token.module';
+import { ApiKeyModule } from '../api-key/api-key.module';
 
 @Module({
-  imports: [TokenModule, WorkspaceModule],
+  // ApiKeyModule supplies ApiKeyService, injected into JwtStrategy so an
+  // api_key Bearer/cookie token is validated directly (replacing the absent EE
+  // `ee/api-key` dynamic require).
+  imports: [TokenModule, WorkspaceModule, ApiKeyModule],
   controllers: [AuthController],
   providers: [AuthService, SignupService, JwtStrategy],
   exports: [SignupService, AuthService],

apps/server/src/core/auth/dto/jwt-payload.ts

@@ -33,6 +33,17 @@ export type JwtPayload = {
   aiChatId?: string | null;
 };
 
+// The AUTH-PRINCIPAL kind behind a collab token — distinct from `actor`
+// (provenance). Stamped into EVERY newly-minted collab token (#501): 'session'
+// for a normal user/session (incl. the internal AI agent, which is session-
+// backed), 'api_key' when the token was minted by an api-key principal (an
+// external MCP agent). The discriminator keys on the token's ORIGIN, so the
+// collab seam can re-check a revoked api key on connect and reject a claimless
+// token after the rollout grace window. NOT keyed on `actor:'agent'` — the
+// internal agent is 'agent' but session-backed, so it must stay on the no-check
+// path.
+export type CollabPrincipal = 'session' | 'api_key';
+
 export type JwtCollabPayload = {
   sub: string;
   workspaceId: string;
@@ -44,6 +55,13 @@ export type JwtCollabPayload = {
   // Nullable: an external MCP agent has no internal ai_chats row, so it carries
   // an 'agent' actor with a null aiChatId.
   aiChatId?: string | null;
+  // Auth-principal discriminator (#501). Present on every post-rollout token;
+  // its absence on a still-valid token past the grace window is treated as an
+  // error, not trust (fail-closed).
+  principal?: CollabPrincipal;
+  // Only when principal === 'api_key': the minting key's id, so the collab seam
+  // can row-check (and reject) a revoked key on connect.
+  apiKeyId?: string;
 };
 
 export type JwtExchangePayload = {

apps/server/src/core/auth/services/auth.service.ts

@@ -375,10 +375,20 @@ export class AuthService {
     }
   }
 
-  async getCollabToken(user: User, workspaceId: string) {
+  async getCollabToken(
+    user: User,
+    workspaceId: string,
+    // Origin of the request minting this collab token (#501). When the caller is
+    // an api-key principal, its apiKeyId is threaded into the token so the collab
+    // seam can re-check the key on connect (closing api-key -> long-lived-collab
+    // laundering). Absent for a normal session/human request.
+    apiKey?: { apiKeyId: string },
+  ) {
     const token = await this.tokenService.generateCollabToken(
       user,
       workspaceId,
+      undefined,
+      apiKey,
     );
     return { token };
   }

apps/server/src/core/auth/services/token.service.behavior.spec.ts

@@ -1,4 +1,5 @@
 import { ForbiddenException, UnauthorizedException } from '@nestjs/common';
+import * as jwt from 'jsonwebtoken';
 import { TokenService } from './token.service';
 import { JwtType } from '../dto/jwt-payload';
 
@@ -213,4 +214,175 @@ describe('TokenService.generateCollabToken', () => {
       aiChatId: 'chat-456',
     });
   });
+
+  // #501 fail-closed discriminator: EVERY collab token carries a principal.
+  it("defaults principal to 'session' with NO apiKeyId (normal/internal-agent path)", async () => {
+    const { service, jwtService } = makeTokenService();
+    await service.generateCollabToken(makeUser() as never, 'ws-1');
+    const [payload] = jwtService.sign.mock.calls[0];
+    expect(payload.principal).toBe('session');
+    expect(payload).not.toHaveProperty('apiKeyId');
+  });
+
+  it("the internal agent (provenance, NO apiKey) still gets principal='session'", async () => {
+    const { service, jwtService } = makeTokenService();
+    await service.generateCollabToken(
+      makeUser() as never,
+      'ws-1',
+      { actor: 'agent', aiChatId: 'chat-1' },
+    );
+    const [payload] = jwtService.sign.mock.calls[0];
+    // Keyed on api-key ORIGIN, not actor: an is_agent session token is 'session'.
+    expect(payload.principal).toBe('session');
+    expect(payload).not.toHaveProperty('apiKeyId');
+  });
+
+  it("stamps principal='api_key' + apiKeyId when minted by an api-key principal", async () => {
+    const { service, jwtService } = makeTokenService();
+    await service.generateCollabToken(
+      makeUser() as never,
+      'ws-1',
+      undefined,
+      { apiKeyId: 'key-9' },
+    );
+    const [payload] = jwtService.sign.mock.calls[0];
+    expect(payload.principal).toBe('api_key');
+    expect(payload.apiKeyId).toBe('key-9');
+  });
 });
+
+/**
+ * API-key token minting MUST carry NO `exp` claim — the ONLY source of truth for
+ * a key's lifetime/revocation is its `api_keys` row, checked on every request.
+ *
+ * This is a LIVE-bug regression: the shared JwtService is registered with a
+ * global `signOptions.expiresIn` (default '90d') that merges into every sign(),
+ * so an api-key minted through it silently gets exp=now+90d and an "unlimited"
+ * key dies in 90 days. TokenService.generateApiToken mints through a dedicated
+ * no-expiry signer instead. These tests construct the REAL signer (a real secret
+ * via the stubbed EnvironmentService) and decode the produced JWT to assert the
+ * observable property: no `exp`.
+ */
+describe('TokenService.generateApiToken (no exp claim ever)', () => {
+  const APP_SECRET_LOCAL = 'apikey-secret';
+
+  function makeRealSignerService() {
+    // Give the SHARED jwtService a global expiresIn so a regression (minting
+    // through it) would show up as an exp claim — the exact live bug.
+    const { JwtService } = require('@nestjs/jwt');
+    const sharedJwt = new JwtService({
+      secret: APP_SECRET_LOCAL,
+      signOptions: { expiresIn: '90d', issuer: 'Docmost' },
+    });
+    const environmentService = {
+      getAppSecret: () => APP_SECRET_LOCAL,
+    };
+    const service = new (TokenService as unknown as new (
+      ...args: unknown[]
+    ) => TokenService)(sharedJwt, environmentService);
+    return { service };
+  }
+
+  const user = makeUser({ id: 'svc-1', workspaceId: 'ws-1' });
+
+  it('mints an api-key JWT with NO exp claim and issuer Docmost', async () => {
+    const { service } = makeRealSignerService();
+
+    const token = await service.generateApiToken({
+      apiKeyId: 'key-1',
+      user: user as never,
+      workspaceId: 'ws-1',
+    });
+
+    const decoded = jwt.decode(token) as Record<string, unknown>;
+    // The observable security property: no expiry lives in the JWT.
+    expect(decoded.exp).toBeUndefined();
+    expect(decoded).toMatchObject({
+      sub: 'svc-1',
+      apiKeyId: 'key-1',
+      workspaceId: 'ws-1',
+      type: JwtType.API_KEY,
+      iss: 'Docmost',
+    });
+  });
+
+  it('demonstrates the live bug it guards: the SHARED signer WOULD add exp', () => {
+    const { JwtService } = require('@nestjs/jwt');
+    const sharedJwt = new JwtService({
+      secret: APP_SECRET_LOCAL,
+      signOptions: { expiresIn: '90d', issuer: 'Docmost' },
+    });
+    // Even with empty per-call options the global expiresIn merges in.
+    const leaky = sharedJwt.sign({ sub: 'x', type: JwtType.API_KEY }, {});
+    expect((jwt.decode(leaky) as Record<string, unknown>).exp).toBeDefined();
+  });
+
+  it('refuses to mint for a disabled user', async () => {
+    const { service } = makeRealSignerService();
+    await expect(
+      service.generateApiToken({
+        apiKeyId: 'key-1',
+        user: makeUser({ deactivatedAt: new Date() }) as never,
+        workspaceId: 'ws-1',
+      }),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+/**
+ * verifyJwtOneOf is the type-routing primitive: verify the signature once and
+ * assert the token type is on an explicit allowlist. It must NOT degrade into a
+ * "return whatever type" helper — a token whose type is off the allowlist is
+ * rejected with the same generic error as a single-type mismatch.
+ */
+describe('TokenService.verifyJwtOneOf (allowlist type-routing)', () => {
+  it('returns the payload when the type is on the allowlist', async () => {
+    const verifyAsync = jest
+      .fn()
+      .mockResolvedValue({ type: JwtType.API_KEY, sub: 'u-1' });
+    const { service } = makeTokenService({ verifyAsync });
+
+    const payload = await service.verifyJwtOneOf(token123(), [
+      JwtType.ACCESS,
+      JwtType.API_KEY,
+    ]);
+
+    expect(payload).toMatchObject({ type: JwtType.API_KEY, sub: 'u-1' });
+    expect(verifyAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('accepts the OTHER allowed type too', async () => {
+    const verifyAsync = jest
+      .fn()
+      .mockResolvedValue({ type: JwtType.ACCESS, sub: 'u-1' });
+    const { service } = makeTokenService({ verifyAsync });
+
+    await expect(
+      service.verifyJwtOneOf(token123(), [JwtType.ACCESS, JwtType.API_KEY]),
+    ).resolves.toMatchObject({ type: JwtType.ACCESS });
+  });
+
+  it('rejects a token whose type is OFF the allowlist (confused-deputy guard)', async () => {
+    const verifyAsync = jest
+      .fn()
+      .mockResolvedValue({ type: JwtType.COLLAB, sub: 'u-1' });
+    const { service } = makeTokenService({ verifyAsync });
+
+    await expect(
+      service.verifyJwtOneOf(token123(), [JwtType.ACCESS, JwtType.API_KEY]),
+    ).rejects.toBeInstanceOf(UnauthorizedException);
+  });
+
+  it('verifies the signature exactly ONCE', async () => {
+    const verifyAsync = jest
+      .fn()
+      .mockResolvedValue({ type: JwtType.ACCESS });
+    const { service } = makeTokenService({ verifyAsync });
+    await service.verifyJwtOneOf(token123(), [JwtType.ACCESS]);
+    expect(verifyAsync).toHaveBeenCalledTimes(1);
+  });
+});
+
+function token123(): string {
+  return 'a.b.c';
+}

apps/server/src/core/auth/services/token.service.ts

@@ -4,7 +4,6 @@ import {
   UnauthorizedException,
 } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
-import type { StringValue } from 'ms';
 import { EnvironmentService } from '../../../integrations/environment/environment.service';
 import {
   JwtApiKeyPayload,
@@ -62,6 +61,12 @@ export class TokenService {
     // token carries no actor/aiChatId and is treated as 'user' downstream.
     // aiChatId is nullable for an external agent with no internal ai_chats row.
     provenance?: { actor: 'agent'; aiChatId: string | null },
+    // Optional api-key origin (#501). When the collab token is minted by an
+    // api-key principal (an external MCP agent), the caller passes the key id so
+    // the token carries principal='api_key' + apiKeyId and the collab seam can
+    // re-check the key on connect. Absent -> principal='session' (a normal
+    // user/session, including the internal session-backed AI agent).
+    apiKey?: { apiKeyId: string },
   ): Promise<string> {
     if (isUserDisabled(user)) {
       throw new ForbiddenException();
@@ -71,6 +76,10 @@ export class TokenService {
       sub: user.id,
       workspaceId,
       type: JwtType.COLLAB,
+      // Fail-closed discriminator on EVERY minted token: 'api_key' when minted by
+      // an api-key principal, else 'session'.
+      principal: apiKey ? 'api_key' : 'session',
+      ...(apiKey ? { apiKeyId: apiKey.apiKeyId } : {}),
       ...(provenance
         ? { actor: provenance.actor, aiChatId: provenance.aiChatId }
         : {}),
@@ -123,9 +132,8 @@ export class TokenService {
     apiKeyId: string;
     user: User;
     workspaceId: string;
-    expiresIn?: StringValue | number;
   }): Promise<string> {
-    const { apiKeyId, user, workspaceId, expiresIn } = opts;
+    const { apiKeyId, user, workspaceId } = opts;
     if (isUserDisabled(user)) {
       throw new ForbiddenException();
     }
@@ -137,7 +145,32 @@ export class TokenService {
       type: JwtType.API_KEY,
     };
 
-    return this.jwtService.sign(payload, expiresIn ? { expiresIn } : {});
+    // API-key tokens carry NO `exp` claim EVER — the ONLY source of truth for a
+    // key's lifetime and revocation is its `api_keys` row (checked on every
+    // request), not the JWT. This CANNOT use `this.jwtService`: TokenModule
+    // registers it with a global `signOptions.expiresIn` (JWT_TOKEN_EXPIRES_IN,
+    // default '90d'), which merges into EVERY sign() call — even `sign(payload,
+    // {})` — and `{ expiresIn: undefined }` THROWS rather than stripping it
+    // (verified empirically). So an "unlimited" key minted through the shared
+    // signer would silently get exp=now+90d and die in 90 days regardless of its
+    // row. We mint through a dedicated no-expiry signer, re-stamping only
+    // `issuer: 'Docmost'` for claim parity with the shared signer.
+    return this.apiKeyJwtService().sign(payload);
+  }
+
+  // Lazily-built JWT signer for API-key tokens: same APP_SECRET, same 'Docmost'
+  // issuer, but WITHOUT the global `expiresIn` — so minted API-key tokens have no
+  // `exp` claim. Built once and cached. Verification still goes through the
+  // shared verifier (same secret); `verifyAsync` does not require an `exp`.
+  private _apiKeyJwtService?: JwtService;
+  private apiKeyJwtService(): JwtService {
+    if (!this._apiKeyJwtService) {
+      this._apiKeyJwtService = new JwtService({
+        secret: this.environmentService.getAppSecret(),
+        signOptions: { issuer: 'Docmost' },
+      });
+    }
+    return this._apiKeyJwtService;
   }
 
   async generatePdfRenderToken(
@@ -177,4 +210,31 @@ export class TokenService {
 
     return payload;
   }
+
+  /**
+   * Verify a token's signature ONCE and assert its `type` is one of `allowed`.
+   *
+   * This is the type-routing primitive for surfaces that legitimately accept
+   * more than one token type on the same Bearer slot (the /mcp Bearer path
+   * accepts both an ACCESS and an API_KEY token). It is deliberately NOT a
+   * "verify-and-return-whatever-type" helper — that would be a reusable
+   * confused-deputy footgun (any caller could then feed an attachment/collab
+   * token where an access token is expected). An explicit allowlist preserves
+   * the type-pinning property of `verifyJwt`: a token whose `type` is not in the
+   * allowlist is rejected with the SAME generic error as a type mismatch, and
+   * the signature is verified exactly once (no double-verify).
+   */
+  async verifyJwtOneOf(token: string, allowed: JwtType[]) {
+    const payload = await this.jwtService.verifyAsync(token, {
+      secret: this.environmentService.getAppSecret(),
+    });
+
+    if (!allowed.includes(payload.type)) {
+      throw new UnauthorizedException(
+        'Invalid JWT token. Token type does not match.',
+      );
+    }
+
+    return payload;
+  }
 }

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

@@ -22,7 +22,8 @@ describe('JwtStrategy — provenance derivation', () => {
     const userSessionRepo: any = { findActiveById: jest.fn() };
     const sessionActivityService: any = { trackActivity: jest.fn() };
     const environmentService: any = { getAppSecret: () => 'test-secret' };
-    const moduleRef: any = {};
+    // ACCESS-path tests never touch the api-key seam; a bare stub suffices.
+    const apiKeyService: any = { validate: jest.fn() };
 
     const strategy = new JwtStrategy(
       userRepo,
@@ -30,7 +31,7 @@ describe('JwtStrategy — provenance derivation', () => {
       userSessionRepo,
       sessionActivityService,
       environmentService,
-      moduleRef,
+      apiKeyService,
     );
     return { strategy, userRepo };
   }
@@ -122,25 +123,29 @@ describe('JwtStrategy — provenance derivation', () => {
 });
 
 /**
- * Provenance derivation on the API-KEY path (jwt.strategy.validateApiKey, #486).
+ * Provenance derivation on the API-KEY path (jwt.strategy.validateApiKey, #486
+ * + #501).
  *
  * The access-token path stamped provenance; the API-key path returned early
  * WITHOUT it, so an is_agent API key's REST writes recorded no 'agent' marker.
  * The API-key payload carries no signed claim, so provenance is resolved from the
- * SERVER-SIDE user returned by ApiKeyService.validateApiKey: isAgent -> 'agent',
+ * SERVER-SIDE user returned by ApiKeyService.validate: isAgent -> 'agent',
  * otherwise 'user'; aiChatId is always null (an API key has no ai_chats row).
  *
- * The enterprise ApiKeyService is not bundled in the OSS build, so the strategy
- * loads it through an overridable `resolveApiKeyService` seam that we stub here.
+ * #501 wires the CORE ApiKeyService (the EE `ee/api-key` module is absent in the
+ * fork) directly into the strategy — no dynamic require. The strategy also stamps
+ * `req.raw.authType='api_key'` + `req.raw.apiKeyId` for the "a token cannot manage
+ * tokens" guard on the /api-keys surface.
  */
-describe('JwtStrategy — API-key provenance derivation (#486)', () => {
-  function makeApiKeyStrategy(validateApiKeyImpl: (p: any) => Promise<any>) {
+describe('JwtStrategy — API-key provenance derivation (#486/#501)', () => {
+  function makeApiKeyStrategy(validateImpl: (p: any) => Promise<any>) {
     const userRepo: any = { findById: jest.fn() };
     const workspaceRepo: any = { findById: jest.fn() };
     const userSessionRepo: any = { findActiveById: jest.fn() };
     const sessionActivityService: any = { trackActivity: jest.fn() };
     const environmentService: any = { getAppSecret: () => 'test-secret' };
-    const moduleRef: any = {};
+    const validate = jest.fn(validateImpl);
+    const apiKeyService: any = { validate };
 
     const strategy = new JwtStrategy(
       userRepo,
@@ -148,14 +153,9 @@ describe('JwtStrategy — API-key provenance derivation (#486)', () => {
       userSessionRepo,
       sessionActivityService,
       environmentService,
-      moduleRef,
+      apiKeyService,
     );
-    // Stub the EE ApiKeyService seam (the real module is not in the OSS build).
-    const validateApiKey = jest.fn(validateApiKeyImpl);
-    jest
-      .spyOn(strategy as any, 'resolveApiKeyService')
-      .mockReturnValue({ validateApiKey });
-    return { strategy, validateApiKey };
+    return { strategy, validate };
   }
 
   const makeReq = () => ({ raw: {} as Record<string, any> });
@@ -166,22 +166,23 @@ describe('JwtStrategy — API-key provenance derivation (#486)', () => {
     type: JwtType.API_KEY,
   });
 
-  it("stamps actor='agent' for an is_agent API key (from the validated user)", async () => {
+  it("stamps actor='agent' + authType/apiKeyId for an is_agent API key", async () => {
     const validated = {
       user: { id: 'svc-1', isAgent: true },
       workspace: { id: 'ws-1' },
     };
-    const { strategy, validateApiKey } = makeApiKeyStrategy(
-      async () => validated,
-    );
+    const { strategy, validate } = makeApiKeyStrategy(async () => validated);
     const req = makeReq();
 
     const result = await strategy.validate(req, apiKeyPayload() as any);
 
-    expect(validateApiKey).toHaveBeenCalledTimes(1);
+    expect(validate).toHaveBeenCalledTimes(1);
     expect(req.raw.actor).toBe('agent');
     // API keys carry no internal ai_chats row -> null.
     expect(req.raw.aiChatId).toBeNull();
+    // Principal-kind markers for the management-surface guard.
+    expect(req.raw.authType).toBe('api_key');
+    expect(req.raw.apiKeyId).toBe('key-1');
     // The validated auth object is returned unchanged (req.user shape preserved).
     expect(result).toBe(validated);
   });
@@ -197,25 +198,19 @@ describe('JwtStrategy — API-key provenance derivation (#486)', () => {
 
     expect(req.raw.actor).toBe('user');
     expect(req.raw.aiChatId).toBeNull();
+    expect(req.raw.authType).toBe('api_key');
   });
 
-  it('throws Unauthorized (and stamps nothing) when the EE module is missing', async () => {
-    const userRepo: any = { findById: jest.fn() };
-    const strategy = new JwtStrategy(
-      userRepo,
-      { findById: jest.fn() } as any,
-      { findActiveById: jest.fn() } as any,
-      { trackActivity: jest.fn() } as any,
-      { getAppSecret: () => 'test-secret' } as any,
-      {} as any,
-    );
-    // EE not bundled: the seam returns null.
-    jest.spyOn(strategy as any, 'resolveApiKeyService').mockReturnValue(null);
+  it('propagates a validate() rejection and stamps nothing', async () => {
+    const { strategy } = makeApiKeyStrategy(async () => {
+      throw new UnauthorizedException();
+    });
     const req = makeReq();
 
     await expect(
       strategy.validate(req, apiKeyPayload() as any),
     ).rejects.toThrow(UnauthorizedException);
     expect(req.raw.actor).toBeUndefined();
+    expect(req.raw.authType).toBeUndefined();
   });
 });

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

@@ -1,4 +1,4 @@
-import { Injectable, Logger, UnauthorizedException } from '@nestjs/common';
+import { Injectable, UnauthorizedException } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 import { Strategy } from 'passport-jwt';
 import { EnvironmentService } from '../../../integrations/environment/environment.service';
@@ -9,20 +9,18 @@ import { UserSessionRepo } from '@docmost/db/repos/session/user-session.repo';
 import { SessionActivityService } from '../../session/session-activity.service';
 import { FastifyRequest } from 'fastify';
 import { extractBearerTokenFromHeader, isUserDisabled } from '../../../common/helpers';
-import { ModuleRef } from '@nestjs/core';
 import { resolveProvenance } from '../../../common/decorators/auth-provenance.decorator';
+import { ApiKeyService } from '../../api-key/api-key.service';
 
 @Injectable()
 export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
-  private logger = new Logger('JwtStrategy');
-
   constructor(
     private userRepo: UserRepo,
     private workspaceRepo: WorkspaceRepo,
     private userSessionRepo: UserSessionRepo,
     private sessionActivityService: SessionActivityService,
     private readonly environmentService: EnvironmentService,
-    private moduleRef: ModuleRef,
+    private readonly apiKeyService: ApiKeyService,
   ) {
     super({
       jwtFromRequest: (req: FastifyRequest) => {
@@ -102,12 +100,17 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
   }
 
   private async validateApiKey(req: any, payload: JwtApiKeyPayload) {
-    const apiKeyService = this.resolveApiKeyService();
-    if (!apiKeyService) {
-      throw new UnauthorizedException('Enterprise API Key module missing');
-    }
+    // The fork ships the core `ApiKeyService` (the EE `ee/api-key` module is
+    // absent). `validate` throws a bare UnauthorizedException on any definite
+    // deny (missing/revoked/expired row, disabled user, kill-switch off) and
+    // propagates infra errors (→ 5xx) rather than masking them as a 401.
+    const result = await this.apiKeyService.validate(payload);
 
-    const result = await apiKeyService.validateApiKey(payload);
+    // Stamp the principal kind + key id so the /api-keys management surface can
+    // enforce "a token cannot manage tokens". Done in this branch because it
+    // returns before the shared ACCESS-path stamping below.
+    req.raw.authType = 'api_key';
+    req.raw.apiKeyId = payload.apiKeyId;
 
     // Stamp the agent-edit provenance for the API-KEY path too (#486). Unlike the
     // access-token path above, it CANNOT be resolved before this point: the
@@ -119,32 +122,10 @@ export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
     // SERVER-SIDE user (never a client field), so an 'agent' badge is unspoofable
     // — mirroring the access-token path. Passing `null` for the claim means the
     // actor is decided solely by user.isAgent.
-    const provenance = resolveProvenance((result as any)?.user, null);
+    const provenance = resolveProvenance(result.user, null);
     req.raw.actor = provenance.actor;
     req.raw.aiChatId = provenance.aiChatId;
 
     return result;
   }
-
-  /**
-   * Resolve the enterprise ApiKeyService, or `null` when the EE module is not
-   * bundled in this build (community build). Extracted as an overridable seam so
-   * the API-key provenance stamping can be unit-tested without the EE package
-   * present (docmost is OSS + a separate EE bundle; `require` of the EE path
-   * throws here). Any load/resolve error is treated as "module missing".
-   */
-  protected resolveApiKeyService(): {
-    validateApiKey: (payload: JwtApiKeyPayload) => Promise<unknown>;
-  } | null {
-    try {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      const ApiKeyModule = require('./../../../ee/api-key/api-key.service');
-      return this.moduleRef.get(ApiKeyModule.ApiKeyService, { strict: false });
-    } catch (err) {
-      this.logger.debug(
-        'API Key module requested but enterprise module not bundled in this build',
-      );
-      return null;
-    }
-  }
 }

apps/server/src/core/core.module.ts

@@ -6,6 +6,7 @@ import {
 } from '@nestjs/common';
 import { UserModule } from './user/user.module';
 import { AuthModule } from './auth/auth.module';
+import { ApiKeyModule } from './api-key/api-key.module';
 import { WorkspaceModule } from './workspace/workspace.module';
 import { PageModule } from './page/page.module';
 import { AttachmentModule } from './attachment/attachment.module';
@@ -29,6 +30,7 @@ import { ClsMiddleware } from 'nestjs-cls';
   imports: [
     UserModule,
     AuthModule,
+    ApiKeyModule,
     WorkspaceModule,
     PageModule,
     AttachmentModule,

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

@@ -10,6 +10,12 @@ import { Transform } from 'class-transformer';
 
 export type ContentFormat = 'json' | 'markdown' | 'html';
 
+// READ-only rendering formats for `getPage` (#502). A superset of the writable
+// `ContentFormat` with `text` — a flat, deterministic, machine-diffable text
+// rendering — added. Kept SEPARATE from `ContentFormat` so the write path
+// (createPage/updatePage `parseProsemirrorContent`) can never be handed `text`.
+export type PageReadFormat = ContentFormat | 'text';
+
 export class CreatePageDto {
   @IsOptional()
   @IsString()

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

@@ -5,10 +5,11 @@ import {
   IsOptional,
   IsString,
   IsUUID,
+  MaxLength,
 } from 'class-validator';
 import { Transform } from 'class-transformer';
 
-import { ContentFormat } from './create-page.dto';
+import { PageReadFormat } from './create-page.dto';
 import { IsPageIdOrSlugId } from './page-identity.validator';
 
 export class PageIdDto {
@@ -43,8 +44,19 @@ export class PageInfoDto extends PageIdDto {
 
   @IsOptional()
   @Transform(({ value }) => value?.toLowerCase())
-  @IsIn(['json', 'markdown', 'html'])
-  format?: ContentFormat;
+  @IsIn(['json', 'markdown', 'html', 'text'])
+  format?: PageReadFormat;
+}
+
+export class PageWorkTimeDto extends PageIdDto {
+  // Viewer IANA timezone for the per-day punch-card buckets (§6.3). Optional —
+  // falls back to UTC server-side. Length-capped so a bogus value cannot bloat
+  // the request; the value is only ever handed to Intl.DateTimeFormat, which
+  // throws on an unknown zone (caught by the controller → 400).
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  tz?: string;
 }
 
 export class DeletePageDto extends PageIdDto {

apps/server/src/core/page/page.controller.getpage-format.spec.ts

@@ -0,0 +1,76 @@
+import { NotFoundException } from '@nestjs/common';
+import { PageController } from './page.controller';
+import { jsonToText, jsonToMarkdown } from '../../collaboration/collaboration.util';
+
+// #502 READ: getPage `format:"text"` routes through the deterministic jsonToText
+// path (placeholders for non-text nodes, block-per-line), while `format:"json"`
+// (or none) returns the raw content and `format:"markdown"` still converts. This
+// pins the CONTROLLER wiring with lightweight mocks (no DB needed — the jsonToText
+// output contract itself is pinned in json-to-text-deterministic.spec.ts).
+
+const CONTENT = {
+  type: 'doc',
+  content: [
+    { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'Config' }] },
+    {
+      type: 'paragraph',
+      content: [
+        { type: 'text', text: 'key=', marks: [{ type: 'bold' }] },
+        { type: 'text', text: 'value' },
+      ],
+    },
+    { type: 'image', attrs: { src: 's' } },
+  ],
+};
+
+function makeController(page: any): PageController {
+  const pageRepo = { findById: jest.fn().mockResolvedValue(page) } as any;
+  const pageAccessService = {
+    validateCanViewWithPermissions: jest
+      .fn()
+      .mockResolvedValue({ canEdit: true, hasRestriction: false }),
+  } as any;
+  // Only pageRepo + pageAccessService are exercised by getPage; the rest are
+  // never touched on this path, so undefined placeholders are fine.
+  return new PageController(
+    undefined as any, // pageService
+    pageRepo,
+    undefined as any, // pageHistoryService
+    undefined as any, // spaceAbility
+    pageAccessService,
+    undefined as any, // backlinkService
+    undefined as any, // labelService
+    undefined as any, // auditService
+  );
+}
+
+const user = { id: 'u1' } as any;
+
+describe('PageController.getPage — format:"text" (#502)', () => {
+  it('returns deterministic flat text with placeholders for non-text nodes', async () => {
+    const controller = makeController({ id: 'p1', content: CONTENT });
+    const res: any = await controller.getPage({ pageId: 'p1', format: 'text' } as any, user);
+    expect(res.content).toBe(jsonToText(CONTENT, { deterministic: true }));
+    expect(res.content).toBe('Config\nkey=value\n[image]');
+    expect(res.permissions).toEqual({ canEdit: true, hasRestriction: false });
+  });
+
+  it('markdown format still converts to markdown (unchanged)', async () => {
+    const controller = makeController({ id: 'p1', content: CONTENT });
+    const res: any = await controller.getPage({ pageId: 'p1', format: 'markdown' } as any, user);
+    expect(res.content).toBe(jsonToMarkdown(CONTENT));
+  });
+
+  it('json / no format returns the raw ProseMirror content object', async () => {
+    const controller = makeController({ id: 'p1', content: CONTENT });
+    const res: any = await controller.getPage({ pageId: 'p1' } as any, user);
+    expect(res.content).toEqual(CONTENT); // untouched object, not a string
+  });
+
+  it('missing page -> NotFoundException', async () => {
+    const controller = makeController(null);
+    await expect(
+      controller.getPage({ pageId: 'nope', format: 'text' } as any, user),
+    ).rejects.toBeInstanceOf(NotFoundException);
+  });
+});

apps/server/src/core/page/page.controller.spec.ts

@@ -1,3 +1,8 @@
+import {
+  BadRequestException,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
 import { PageController } from './page.controller';
 
 // Direct instantiation with stub deps. The Test.createTestingModule form failed
@@ -22,4 +27,88 @@ describe('PageController', () => {
   it('should be defined', () => {
     expect(controller).toBeDefined();
   });
+
+  // #395 — the work-time endpoint must be gated exactly like /history.
+  describe('getPageWorkTime', () => {
+    const user = { id: 'u1' } as any;
+
+    function build(overrides: {
+      page?: any;
+      validate?: jest.Mock;
+      compute?: jest.Mock;
+    }) {
+      const pageRepo = { findById: jest.fn().mockResolvedValue(overrides.page) };
+      const pageAccessService = {
+        validateCanView: overrides.validate ?? jest.fn().mockResolvedValue(undefined),
+      };
+      const pageHistoryService = {
+        computeWorkTime:
+          overrides.compute ?? jest.fn().mockResolvedValue({ workMs: 0 }),
+      };
+      const c = new PageController(
+        {} as any,
+        pageRepo as any,
+        pageHistoryService as any,
+        {} as any,
+        pageAccessService as any,
+        {} as any,
+        {} as any,
+        {} as any,
+      );
+      return { c, pageRepo, pageAccessService, pageHistoryService };
+    }
+
+    it('404s when the page does not exist', async () => {
+      const { c } = build({ page: null });
+      await expect(
+        c.getPageWorkTime({ pageId: 'p1' } as any, user),
+      ).rejects.toBeInstanceOf(NotFoundException);
+    });
+
+    it('enforces validateCanView before computing, then delegates with tz', async () => {
+      const validate = jest.fn().mockResolvedValue(undefined);
+      const compute = jest.fn().mockResolvedValue({ workMs: 42 });
+      const { c } = build({ page: { id: 'pg' }, validate, compute });
+      const out = await c.getPageWorkTime(
+        { pageId: 'pg', tz: 'Europe/Moscow' } as any,
+        user,
+      );
+      expect(validate).toHaveBeenCalledWith({ id: 'pg' }, user);
+      expect(compute).toHaveBeenCalledWith('pg', 'Europe/Moscow');
+      expect(out).toEqual({ workMs: 42 });
+    });
+
+    it('propagates a denied view gate and does NOT reach compute (security)', async () => {
+      // If validateCanView is moved AFTER computeWorkTime, the timeline of a page
+      // the caller may not see would be read/estimated before the gate — this
+      // locks the order: a rejecting gate must short-circuit before any compute.
+      const validate = jest.fn().mockRejectedValue(new ForbiddenException());
+      const compute = jest.fn().mockResolvedValue({ workMs: 1 });
+      const { c, pageHistoryService } = build({
+        page: { id: 'pg' },
+        validate,
+        compute,
+      });
+      await expect(
+        c.getPageWorkTime({ pageId: 'pg' } as any, user),
+      ).rejects.toBeInstanceOf(ForbiddenException);
+      expect(pageHistoryService.computeWorkTime).not.toHaveBeenCalled();
+    });
+
+    it('maps an unknown-timezone RangeError to a 400', async () => {
+      const compute = jest.fn().mockRejectedValue(new RangeError('bad tz'));
+      const { c } = build({ page: { id: 'pg' }, compute });
+      await expect(
+        c.getPageWorkTime({ pageId: 'pg', tz: 'X/Y' } as any, user),
+      ).rejects.toBeInstanceOf(BadRequestException);
+    });
+
+    it('does not swallow a non-RangeError from the service', async () => {
+      const compute = jest.fn().mockRejectedValue(new Error('db down'));
+      const { c } = build({ page: { id: 'pg' }, compute });
+      await expect(
+        c.getPageWorkTime({ pageId: 'pg' } as any, user),
+      ).rejects.toThrow('db down');
+    });
+  });
 });

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

@@ -21,6 +21,7 @@ import {
   PageHistoryIdDto,
   PageIdDto,
   PageInfoDto,
+  PageWorkTimeDto,
 } from './dto/page.dto';
 import { PageHistoryService } from './services/page-history.service';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
@@ -49,6 +50,7 @@ import { AddLabelsDto, RemoveLabelDto } from '../label/dto/label.dto';
 import {
   jsonToHtml,
   jsonToMarkdown,
+  jsonToText,
 } from '../../collaboration/collaboration.util';
 import { AuditEvent, AuditResource } from '../../common/events/audit-events';
 import {
@@ -93,10 +95,16 @@ export class PageController {
     const permissions = { canEdit, hasRestriction };
 
     if (dto.format && dto.format !== 'json' && page.content) {
-      const contentOutput =
-        dto.format === 'markdown'
-          ? jsonToMarkdown(page.content)
-          : jsonToHtml(page.content);
+      let contentOutput: string;
+      if (dto.format === 'markdown') {
+        contentOutput = jsonToMarkdown(page.content);
+      } else if (dto.format === 'text') {
+        // #502: flat, deterministic, machine-diffable text (block-per-line,
+        // inline marks/anchors dropped, non-text nodes -> stable placeholders).
+        contentOutput = jsonToText(page.content, { deterministic: true });
+      } else {
+        contentOutput = jsonToHtml(page.content);
+      }
       return {
         ...page,
         content: contentOutput,
@@ -524,6 +532,32 @@ export class PageController {
     return this.pageHistoryService.findHistoryByPageId(page.id, pagination);
   }
 
+  @HttpCode(HttpStatus.OK)
+  @Post('/history/time')
+  async getPageWorkTime(
+    @Body() dto: PageWorkTimeDto,
+    @AuthUser() user: User,
+  ) {
+    const page = await this.pageRepo.findById(dto.pageId);
+    if (!page) {
+      throw new NotFoundException('Page not found');
+    }
+
+    // Same view gate as /history and /history/info.
+    await this.pageAccessService.validateCanView(page, user);
+
+    try {
+      return await this.pageHistoryService.computeWorkTime(page.id, dto.tz);
+    } catch (e) {
+      // Intl.DateTimeFormat throws RangeError on an unknown IANA zone; surface
+      // it as a 400 rather than a 500.
+      if (e instanceof RangeError) {
+        throw new BadRequestException('Invalid timezone');
+      }
+      throw e;
+    }
+  }
+
   @HttpCode(HttpStatus.OK)
   @Post('/history/info')
   async getPageHistoryInfo(
@@ -818,6 +852,11 @@ export class PageController {
       throw new NotFoundException('Page not found');
     }
 
+    // Target-only validateCanView is intentional: getPageBreadCrumbs returns
+    // the full ancestor chain WITHOUT per-ancestor permission filtering. Safe
+    // because page restrictions inherit down the tree, so any ancestor the
+    // caller could not view would already hide the target here — see the
+    // getPageBreadCrumbs docstring / #471.
     await this.pageAccessService.validateCanView(page, user);
 
     return this.pageService.getPageBreadCrumbs(page.id);