fix(work-time): clip cross-class padding; gate & payload fixes (#395)

F1: pad-clip adjacent different-class sessions at the raw-gap midpoint so
workMs and agentOnlyMs can never double-count the same wall-clock (default
agentTGap 7m < pIn+pOut 10m made a work-session-ending-in-agent overlap a
nearby agent_only run). Reword the config guard/comment: cross-class
disjointness is now structural, tGap≥pIn+pOut is a kept sanity bound. Add a
cross-class no-double-count test and a real seeded property/fuzz test (250
random timelines × 4 tz) asserting per-class union, cross-class disjointness,
and Σ per-day activeMs == workMs.

F2: page.controller.spec — add a ForbiddenException view-gate reject test that
asserts the rejection propagates and computeWorkTime is NOT reached, locking
validateCanView before compute.

F3: WorkTimeStat renders for agent-only pages (workMs==0, agentOnlyMs>0) with
an `agent:` headline so the punch-card stays reachable.

F4: drop the dead un-bucketed `sessions` list from the PageWorkTime response
and the client work-time types (no client reads it; bucketByDay still consumes
the core sessions internally).

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
 

CHANGELOG.md

@@ -392,6 +392,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/

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

@@ -1427,5 +1427,20 @@
   "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",
+  "≈ {{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

@@ -1442,5 +1442,20 @@
   "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": "Агент",
+  "≈ {{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/features/ai-chat/components/chat-thread.test.tsx

@@ -1254,88 +1254,4 @@ describe("ChatThread — live reconnect + stalled", () => {
     });
     expect(onResumeFallback).toHaveBeenCalledWith(false); // POLL_IDLE_CAP -> idle -> disarm
   });
-
-  it("#541: getRun HANGS on a live disconnect — the timeout race still enters reconnect (no silent freeze in `streaming`)", async () => {
-    // MUTATION-VERIFY: revert the race to a bare `getRun(cid).then/.catch` and this
-    // reddens — a HUNG (never-settling, NOT rejected) getRun leaves the FSM stuck in
-    // `streaming` with no reconnect banner and no poll (the axios client sets no
-    // request timeout, and the stalled-idle cap only arms AFTER reconnecting/polling).
-    renderLive();
-    h.state.getRun.mockReset();
-    h.state.getRun.mockReturnValue(new Promise(() => {})); // getRun HANGS forever
-    await disconnect(); // live partial = liveMsg (id "a2")
-    expect(h.state.getRun).toHaveBeenCalledWith("c1");
-    // BEFORE the bound fires the FSM is still in the live turn — the very freeze bug.
-    expect(screen.queryByText(/reconnecting/i)).toBeNull();
-    // The recovery-start bound fires -> the SAME fallback as the reject path.
-    act(() => {
-      vi.advanceTimersByTime(4_000);
-    });
-    expect(screen.getByText(/reconnecting/i)).toBeTruthy();
-    // The live partial (a2) was DROPPED from the store (replay-from-start, no stale
-    // tail-apply base). Mirrors the getRun-REJECT test's inspection.
-    const removedLivePartial = (
-      h.state.setMessages as unknown as {
-        mock: { calls: [unknown][] };
-      }
-    ).mock.calls.some(([updater]) => {
-      if (typeof updater !== "function") return false;
-      const out = (updater as (p: { id: string }[]) => { id: string }[])([
-        { id: "a2" },
-        { id: "u1" },
-      ]);
-      return !out.some((m) => m.id === "a2");
-    });
-    expect(removedLivePartial).toBe(true);
-    // ...and the anchor was NULLED -> replay-from-start (no ?anchor=&n= over the partial).
-    advanceToAttempt(1);
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
-    expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream",
-    );
-  });
-
-  it("#541: a getRun resolve AFTER the timeout already fired is IGNORED (no double reconnect, no stale re-seed)", async () => {
-    // The timeout wins first and enters the ladder via replay-from-start. When the
-    // hung getRun FINALLY answers, its late `.then` must be a full no-op: it must not
-    // re-seed the store from the (now stale) persisted row, must not re-set the
-    // anchor, and must not re-enter reconnect. The local `settled` flag makes the
-    // resolve/reject/timeout branches mutually exclusive.
-    // MUTATION-VERIFY: drop the `settled` guard (let the late `.then` run) and the
-    // late re-seed re-sets the anchor (URL regains ?anchor=a2&n=3) + calls setMessages.
-    renderLive();
-    let resolveGetRun!: (v: unknown) => void;
-    h.state.getRun.mockReset();
-    h.state.getRun.mockReturnValue(
-      new Promise((r) => {
-        resolveGetRun = r;
-      }),
-    );
-    await disconnect();
-    act(() => {
-      vi.advanceTimersByTime(4_000); // bound fires -> replay-from-start, reconnecting
-    });
-    expect(screen.getByText(/reconnecting/i)).toBeTruthy();
-    advanceToAttempt(1);
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
-    // Anchor is null -> replay-from-start URL (the pre-condition the late resolve must
-    // not undo).
-    expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream",
-    );
-    const setMessagesCallsBefore = h.state.setMessages.mock.calls.length;
-    // NOW the hung getRun finally resolves with a persisted anchor (id a2, steps 3).
-    await act(async () => {
-      resolveGetRun(persistedAnchor());
-      await Promise.resolve();
-    });
-    // The late resolve did NOT re-seed the store...
-    expect(h.state.setMessages.mock.calls.length).toBe(setMessagesCallsBefore);
-    // ...did NOT re-set the anchor (URL stays replay-from-start, no ?anchor=&n=)...
-    expect(h.state.transport!.prepareReconnectToStreamRequest!().api).toBe(
-      "/api/ai-chat/runs/c1/stream",
-    );
-    // ...and did NOT trigger a fresh reconnect attach.
-    expect(h.state.resumeStream).toHaveBeenCalledTimes(1);
-  });
 });

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

@@ -81,17 +81,6 @@ const STREAM_THROTTLE_MS = 50;
 // THREAD now (the FSM owns polling->stalled); the window just polls while armed.
 const DEGRADED_POLL_IDLE_MAX_MS = 10 * 60_000;
 
-// #541: the bound on the persist re-seed (getRun) wait when ENTERING the reconnect
-// ladder after a live SSE drop. The axios client (lib/api-client.ts) sets NO request
-// timeout, and the stalled-idle cap only arms AFTER the FSM enters reconnecting/
-// polling — which never happens if getRun HANGS (connection established, no response).
-// Without this bound a live drop + a hung getRun sticks the FSM in `streaming` with
-// no banner and no poll until the browser socket timeout (minutes) — the silent-freeze
-// class #497 eliminates. This is a deliberate RECOVERY-START bound (drop the live
-// partial + enter the ladder so the poll/idle-cap arms), intentionally much shorter
-// than any network socket timeout — not a network read timeout.
-const RECONNECT_RESEED_TIMEOUT_MS = 4_000;
-
 /** The #487 active (non-terminal) run statuses — mirrors the server's
  *  ACTIVE_RUN_STATUSES. A run-fact is "active" only for these. */
 function isActiveRunStatus(status: string | null | undefined): boolean {
@@ -297,9 +286,6 @@ export default function ChatThread({
   // stalled inactivity cap. Cleared by the cancelReconnect effect / the cap effect.
   const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const idleCapTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  // #541: the persist re-seed (getRun) timeout race on the disconnect->reconnect
-  // entry. Held in a ref so unmount (DISPOSE cleanup) clears it — no dangling timer.
-  const reseedTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   // #491 tail-only: seed EVERY persisted row unchanged (no strip). The streaming
   // tail holds steps 0..N-1; the run-stream registry's tail (steps >= N) is APPENDED
@@ -762,67 +748,36 @@ export default function ChatThread({
           anchorRef.current = null;
         };
         if (cid) {
-          // #541: bound the persist re-seed wait with a timeout race. getRun goes
-          // through the axios client, which has NO request timeout; a HUNG getRun
-          // (connection open, no response) — distinct from a REJECT, which the
-          // `.catch` already handles — would otherwise never let us enter the ladder,
-          // leaving the FSM stuck in `streaming` with no banner and no poll until the
-          // browser socket timeout. `settled` makes the three branches (resolve /
-          // reject / timeout) mutually exclusive: whichever fires FIRST wins and the
-          // others become no-ops. So a LATE getRun resolve AFTER the timeout is fully
-          // ignored — it cannot (i) re-enter reconnect a second time, (ii) overwrite
-          // the timeout's replay-from-start with a stale re-seed, or (iii) re-arm any
-          // timer. On timeout we take the SAME fallback as the reject path (drop the
-          // live partial + enter the ladder, so the poll and the stalled-idle cap arm).
-          let settled = false;
-          const finishReseed = (apply: () => void): void => {
-            if (settled) return;
-            settled = true;
-            if (reseedTimerRef.current) {
-              clearTimeout(reseedTimerRef.current);
-              reseedTimerRef.current = null;
-            }
-            if (!mountedRef.current) return;
-            apply();
-          };
-          reseedTimerRef.current = setTimeout(() => {
-            finishReseed(() => {
-              dropLivePartialAndReplayFromStart();
-              enterReconnect(runId);
-            });
-          }, RECONNECT_RESEED_TIMEOUT_MS);
           void getRun(cid)
             .then((res) => {
-              finishReseed(() => {
-                const persisted = res.message;
-                if (persisted && persisted.role === "assistant") {
-                  anchorRef.current = {
-                    id: persisted.id,
-                    stepsPersisted: stepsPersistedOf(persisted),
-                  };
-                  // Replace the live partial with the persisted row IN PLACE by id —
-                  // the re-seed from persist. The attach's tail (steps >= N) then
-                  // appends to a store holding EXACTLY steps 0..N-1: no duplication.
-                  setMessages((prev) => mergeById(prev, rowToUiMessage(persisted)));
-                } else {
-                  // No persisted assistant row (pre-first-frame break): drop the live
-                  // partial + replay from start (no anchor/n) so nothing is duplicated.
-                  dropLivePartialAndReplayFromStart();
-                }
-                enterReconnect(res.run?.id ?? runId);
-              });
+              if (!mountedRef.current) return;
+              const persisted = res.message;
+              if (persisted && persisted.role === "assistant") {
+                anchorRef.current = {
+                  id: persisted.id,
+                  stepsPersisted: stepsPersistedOf(persisted),
+                };
+                // Replace the live partial with the persisted row IN PLACE by id —
+                // the re-seed from persist. The attach's tail (steps >= N) then
+                // appends to a store holding EXACTLY steps 0..N-1: no duplication.
+                setMessages((prev) => mergeById(prev, rowToUiMessage(persisted)));
+              } else {
+                // No persisted assistant row (pre-first-frame break): drop the live
+                // partial + replay from start (no anchor/n) so nothing is duplicated.
+                dropLivePartialAndReplayFromStart();
+              }
+              enterReconnect(res.run?.id ?? runId);
             })
             .catch(() => {
-              finishReseed(() => {
-                // Persist read FAILED: we cannot re-seed from fresh persist, and a
-                // stale mount-time anchor over the live partial would tail-apply
-                // already-present steps -> duplication (a flaky-network blip:
-                // SSE + getRun both fail, network recovers in ~1s, the registry still
-                // covers from the mount frontier). Restore the removed-filter guarantee
-                // instead: drop the live partial + replay from start / 204 -> poll.
-                dropLivePartialAndReplayFromStart();
-                enterReconnect(runId);
-              });
+              if (!mountedRef.current) return;
+              // Persist read FAILED: we cannot re-seed from fresh persist, and a
+              // stale mount-time anchor over the live partial would tail-apply
+              // already-present steps -> duplication (a flaky-network blip:
+              // SSE + getRun both fail, network recovers in ~1s, the registry still
+              // covers from the mount frontier). Restore the removed-filter guarantee
+              // instead: drop the live partial + replay from start / 204 -> poll.
+              dropLivePartialAndReplayFromStart();
+              enterReconnect(runId);
             });
         } else {
           dropLivePartialAndReplayFromStart();
@@ -948,12 +903,6 @@ export default function ChatThread({
     }
     return () => {
       mountedRef.current = false;
-      // #541: clear the in-flight persist re-seed timeout (not an FSM effect timer,
-      // so DISPOSE does not touch it) — no dangling setTimeout after unmount.
-      if (reseedTimerRef.current) {
-        clearTimeout(reseedTimerRef.current);
-        reseedTimerRef.current = null;
-      }
       dispatch({ type: "DISPOSE" }); // aborts attach + timers, bumps epoch (I5)
     };
     // Mount-only by design; the parent remounts per chat via `key`.

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-punch-card.tsx

@@ -0,0 +1,171 @@
+import { Group, Stack, Text } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import { useMemo } from "react";
+import { IPageWorkTime, IPerDay, IDayWindow } from "./work-time.types";
+import {
+  formatDayTotal,
+  formatGapMinutes,
+  formatHeadline,
+} from "./format-work-time";
+import classes from "./work-time.module.css";
+
+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) — the row is still always one day.
+const EMPTY_RUN_COLLAPSE = 8;
+
+type Row =
+  | { type: "day"; day: IPerDay }
+  | { type: "gap"; count: number };
+
+function collapseEmptyRuns(perDay: IPerDay[]): Row[] {
+  const rows: Row[] = [];
+  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: d });
+    }
+    emptyRun = [];
+  };
+  for (const d of perDay) {
+    if (d.activeMs === 0 && d.agentMs === 0) {
+      emptyRun.push(d);
+    } else {
+      flush();
+      rows.push({ type: "day", day: d });
+    }
+  }
+  flush();
+  return rows;
+}
+
+function dayHeading(day: number): string {
+  return new Date(day).toLocaleDateString(undefined, {
+    weekday: "short",
+    day: "numeric",
+    month: "short",
+  });
+}
+
+function DayTrack({
+  day,
+  pSingle,
+}: {
+  day: IPerDay;
+  pSingle: number;
+}) {
+  const { t } = useTranslation();
+  const ticks = [6, 12, 18];
+  return (
+    <div className={classes.row}>
+      <span className={classes.dayLabel}>{dayHeading(day.day)}</span>
+      <div className={classes.track}>
+        {ticks.map((h) => (
+          <div
+            key={h}
+            className={classes.hourTick}
+            style={{ left: `${(h / 24) * 100}%` }}
+          />
+        ))}
+        {day.windows.map((w: IDayWindow, i) => {
+          const leftPct = ((w.start - day.day) / DAY_MS) * 100;
+          const widthPct = ((w.end - w.start) / DAY_MS) * 100;
+          const isSingle = w.end - w.start <= pSingle;
+          const cls = [
+            classes.window,
+            w.class === "work" ? classes.windowWork : classes.windowAgent,
+            isSingle ? classes.windowSingle : "",
+          ].join(" ");
+          return (
+            <div
+              key={i}
+              className={cls}
+              style={{
+                left: `${Math.max(0, Math.min(100, leftPct))}%`,
+                width: `${Math.max(0, Math.min(100, widthPct))}%`,
+              }}
+            />
+          );
+        })}
+      </div>
+      <span className={classes.daySum}>
+        {formatDayTotal(day.activeMs, t)}
+      </span>
+    </div>
+  );
+}
+
+interface Props {
+  data: IPageWorkTime;
+}
+
+export default function WorkTimePunchCard({ data }: Props) {
+  const { t } = useTranslation();
+  const rows = useMemo(() => collapseEmptyRuns(data.perDay), [data.perDay]);
+  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">
+      <Group gap="lg">
+        <Text size="sm" fw={500}>
+          {formatHeadline(data.workMs, t)}
+        </Text>
+        {data.agentOnlyMs > 0 && (
+          <Text size="xs" c="dimmed">
+            {t("agent: {{value}}", { value: formatHeadline(data.agentOnlyMs, t) })}
+          </Text>
+        )}
+      </Group>
+
+      <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>
+
+      <div>
+        {rows.map((row, i) =>
+          row.type === "day" ? (
+            <DayTrack
+              key={row.day.dayISO}
+              day={row.day}
+              pSingle={data.config.pSingle}
+            />
+          ) : (
+            <div key={`gap-${i}`} className={classes.gapRow}>
+              {t("× {{count}} days without edits", { count: row.count })}
+            </div>
+          ),
+        )}
+      </div>
+
+      <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="lg"
+      >
+        <WorkTimePunchCard data={data} />
+      </Modal>
+    </>
+  );
+}

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

@@ -0,0 +1,82 @@
+/* #395 — 24h × days punch-card. Custom CSS segments on a fixed 24-hour track
+   (position = offset-in-day / 24h, width = duration / 24h), no chart library. */
+
+.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 {
+  position: relative;
+  height: 16px;
+  border-radius: 4px;
+  background-color: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-6)
+  );
+  overflow: hidden;
+}
+
+/* Faint hour grid so the eye can read "morning vs evening". */
+.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: 2px;
+  bottom: 2px;
+  border-radius: 3px;
+  min-width: 3px;
+}
+
+.windowWork {
+  background-color: var(--mantine-color-blue-5);
+}
+
+.windowAgent {
+  background-color: var(--mantine-color-grape-5);
+}
+
+/* A lone single-sample (P_single) window: minimal + dimmed, so it neither
+   vanishes nor fakes dense work (§6.2). */
+.windowSingle {
+  opacity: 0.5;
+}
+
+.daySum {
+  font-size: var(--mantine-font-size-xs);
+  text-align: right;
+  white-space: nowrap;
+}
+
+.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/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/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/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/core/ai-chat/ai-chat.service.ts

@@ -189,10 +189,11 @@ export function stepBudgetWarning(stepNumber: number): string {
 //
 // `system` is the in-scope system prompt; we CONCATENATE so the original
 // persona/context is preserved — a bare `system` override would REPLACE the
-// whole system prompt for the step. `activatedTools` is PER-TURN mutable state
-// owned by the streaming loop (a closure Set grown by loadTools); it is passed
-// in (not module-global, not persisted) so this stays a pure function of its
-// arguments.
+// whole system prompt for the step. `activatedTools` is a closure Set grown by
+// loadTools and owned by the streaming loop; the caller seeds it from and
+// persists it to the chat's metadata across turns (#490), but this function only
+// READS the Set it is handed, so it stays a pure function of its arguments (not
+// module-global).
 //
 // NOTE: at AI SDK v7 the per-step `system` field is renamed to `instructions`.
 // On v6 (`^6.0.134`) `system` is the correct field — adjust when bumping.
@@ -1410,10 +1411,11 @@ export class AiChatService implements OnModuleInit, OnModuleDestroy {
       const baseTools = { ...external.tools, ...docmostTools };
 
       // Deferred tool loading state (#332), scoped to THIS streaming loop:
-      //  - `activatedTools` is per-TURN mutable state — a fresh closure Set created
-      //    per streamText call, NOT module-global and NOT persisted, so a new turn
-      //    starts cold. loadTools.execute adds to it; prepareAgentStep reads it to
-      //    widen `activeTools` on the NEXT step.
+      //  - `activatedTools` is a fresh closure Set per streamText call (not
+      //    module-global), SEEDED from the chat's persisted metadata.activatedTools
+      //    (#490, just below) so activation carries across turns. loadTools.execute
+      //    adds to it; prepareAgentStep reads it to widen `activeTools` on the NEXT
+      //    step; turn end persists it back.
       //  - `validDeferredNames` = every tool that is NOT core (the in-app deferred
       //    tools + ALL external MCP tools), computed from the ACTUAL toolset so an
       //    external tool is loadable by its namespaced name. loadTools rejects any

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/page.dto.ts

@@ -5,6 +5,7 @@ import {
   IsOptional,
   IsString,
   IsUUID,
+  MaxLength,
 } from 'class-validator';
 import { Transform } from 'class-transformer';
 
@@ -47,6 +48,17 @@ export class PageInfoDto extends PageIdDto {
   format?: ContentFormat;
 }
 
+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 {
   @IsOptional()
   @IsBoolean()

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';
@@ -524,6 +525,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(

apps/server/src/core/page/services/page-history.service.ts

@@ -3,6 +3,23 @@ import { PageHistoryRepo } from '@docmost/db/repos/page/page-history.repo';
 import { PageHistory } from '@docmost/db/types/entity.types';
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { CursorPaginationResult } from '@docmost/db/pagination/cursor-pagination';
+import {
+  computeWorkTime,
+  bucketByDay,
+  DEFAULT_WORK_TIME_CONFIG,
+  WorkTimeConfig,
+  PerDay,
+} from '../work-time';
+
+export interface PageWorkTime {
+  workMs: number;
+  agentOnlyMs: number;
+  perDay: PerDay[];
+  /** the config actually used, so the UI can show "≈" + the T_gap threshold. */
+  config: WorkTimeConfig;
+  /** the tz the per-day buckets were computed in (echoed back for the label). */
+  tz: string;
+}
 
 @Injectable()
 export class PageHistoryService {
@@ -23,4 +40,33 @@ export class PageHistoryService {
       paginationOptions,
     );
   }
+
+  /**
+   * #395 — estimate time worked on a page (§5) and bucket it into the viewer's
+   * calendar days for the punch-card (§6.3). Reads only the cheap history
+   * projection (no `content`); the estimate itself is a pure, deterministic
+   * function so it is unit-tested exhaustively without a DB.
+   *
+   * `tz` is the viewer's IANA zone (browser locale) — it moves which day a
+   * session lands in and where its windows sit, but never the total (§10).
+   */
+  async computeWorkTime(
+    pageId: string,
+    tz = 'UTC',
+    config?: Partial<WorkTimeConfig>,
+  ): Promise<PageWorkTime> {
+    const rows = await this.pageHistoryRepo.findTimelineByPageId(pageId);
+    const result = computeWorkTime(rows, config);
+    const usedConfig: WorkTimeConfig = { ...DEFAULT_WORK_TIME_CONFIG, ...config };
+    // `bucketByDay` consumes the pure core's un-bucketed sessions here; the
+    // full session list is NOT shipped on the response (no client reads it).
+    const perDay = bucketByDay(result.sessions, tz);
+    return {
+      workMs: result.workMs,
+      agentOnlyMs: result.agentOnlyMs,
+      perDay,
+      config: usedConfig,
+      tz,
+    };
+  }
 }

apps/server/src/core/page/work-time/bucket-by-day.spec.ts

@@ -0,0 +1,129 @@
+import { bucketByDay, zonedDayStart } from './bucket-by-day';
+import { computeWorkTime } from './compute-work-time';
+import { WorkSession, TimelineSample } from './work-time.types';
+
+const MIN = 60 * 1000;
+const HOUR = 60 * MIN;
+
+function work(start: number, end: number): WorkSession {
+  return { start, end, class: 'work' };
+}
+function agent(start: number, end: number): WorkSession {
+  return { start, end, class: 'agent_only' };
+}
+
+function sumActive(perDay: ReturnType<typeof bucketByDay>): number {
+  return perDay.reduce((a, d) => a + d.activeMs, 0);
+}
+
+describe('bucketByDay', () => {
+  it('Σ activeMs == workMs — the §6.3 consistency invariant', () => {
+    const rows: TimelineSample[] = [
+      { createdAt: '2026-07-04T03:40:00Z', lastUpdatedById: 'h', lastUpdatedSource: 'user', lastUpdatedAiChatId: null, kind: null },
+      { createdAt: '2026-07-04T03:49:00Z', lastUpdatedById: 'h', lastUpdatedSource: 'user', lastUpdatedAiChatId: null, kind: null },
+      { createdAt: '2026-07-04T18:11:00Z', lastUpdatedById: 'h', lastUpdatedSource: 'user', lastUpdatedAiChatId: null, kind: null },
+      { createdAt: '2026-07-06T15:34:00Z', lastUpdatedById: 'h', lastUpdatedSource: 'user', lastUpdatedAiChatId: null, kind: null },
+    ];
+    const r = computeWorkTime(rows);
+    const perDay = bucketByDay(r.sessions, 'UTC');
+    expect(sumActive(perDay)).toBe(r.workMs);
+  });
+
+  it('empty input → no days', () => {
+    expect(bucketByDay([], 'UTC')).toEqual([]);
+  });
+
+  it('midnight-crossing session splits across two days, sum preserved (§9#9)', () => {
+    const start = Date.UTC(2026, 0, 10, 23, 14);
+    const end = Date.UTC(2026, 0, 11, 0, 40);
+    const perDay = bucketByDay([work(start, end)], 'UTC');
+    expect(perDay).toHaveLength(2);
+    expect(perDay[0].dayISO).toBe('2026-01-10');
+    expect(perDay[1].dayISO).toBe('2026-01-11');
+    expect(perDay[0].activeMs).toBe(46 * MIN); // 23:14 → 24:00
+    expect(perDay[1].activeMs).toBe(40 * MIN); // 00:00 → 00:40
+    expect(sumActive(perDay)).toBe(end - start);
+  });
+
+  it('empty days between active days are emitted, not skipped (§9#12)', () => {
+    const d1 = work(Date.UTC(2026, 0, 10, 10, 0), Date.UTC(2026, 0, 10, 11, 0));
+    const d3 = work(Date.UTC(2026, 0, 12, 10, 0), Date.UTC(2026, 0, 12, 11, 0));
+    const perDay = bucketByDay([d1, d3], 'UTC');
+    expect(perDay.map((d) => d.dayISO)).toEqual([
+      '2026-01-10',
+      '2026-01-11',
+      '2026-01-12',
+    ]);
+    expect(perDay[1].activeMs).toBe(0);
+    expect(perDay[1].windows).toEqual([]);
+  });
+
+  it('agent_only windows are drawn but excluded from activeMs', () => {
+    const w = work(Date.UTC(2026, 0, 10, 9, 0), Date.UTC(2026, 0, 10, 10, 0));
+    const a = agent(Date.UTC(2026, 0, 10, 14, 0), Date.UTC(2026, 0, 10, 14, 30));
+    const perDay = bucketByDay([w, a], 'UTC');
+    expect(perDay).toHaveLength(1);
+    expect(perDay[0].activeMs).toBe(1 * HOUR);
+    expect(perDay[0].agentMs).toBe(30 * MIN);
+    expect(perDay[0].windows.map((x) => x.class)).toEqual(['work', 'agent_only']);
+  });
+
+  it('work and agent_only are unioned SEPARATELY (agent does not swallow work)', () => {
+    // Overlapping work + agent windows on the same day.
+    const w = work(Date.UTC(2026, 0, 10, 9, 0), Date.UTC(2026, 0, 10, 11, 0));
+    const a = agent(Date.UTC(2026, 0, 10, 10, 0), Date.UTC(2026, 0, 10, 12, 0));
+    const perDay = bucketByDay([w, a], 'UTC');
+    expect(perDay[0].activeMs).toBe(2 * HOUR);
+    expect(perDay[0].agentMs).toBe(2 * HOUR);
+  });
+
+  it('overlapping same-class sessions are UNIONed, not summed (no double-count)', () => {
+    // Two work sessions that overlap 10:00–10:30 on one day.
+    const a = work(Date.UTC(2026, 0, 10, 9, 0), Date.UTC(2026, 0, 10, 10, 30));
+    const b = work(Date.UTC(2026, 0, 10, 10, 0), Date.UTC(2026, 0, 10, 11, 0));
+    const perDay = bucketByDay([a, b], 'UTC');
+    expect(perDay).toHaveLength(1);
+    // Union 09:00–11:00 = 2h, NOT 90m + 60m = 150m.
+    expect(perDay[0].activeMs).toBe(2 * HOUR);
+    // The drawn windows are also merged to one, so the punch-card cannot render
+    // an overlapping double bar.
+    expect(perDay[0].windows).toHaveLength(1);
+    expect(perDay[0].windows[0].start).toBe(a.start);
+    expect(perDay[0].windows[0].end).toBe(b.end);
+  });
+
+  it('DST fall-back: a full 25-hour day still balances (§9#14)', () => {
+    // America/New_York ends DST 2026-11-01 (25h day).
+    const tz = 'America/New_York';
+    const dayStart = zonedDayStart(Date.UTC(2026, 10, 1, 12, 0), tz);
+    const nextStart = zonedDayStart(dayStart + 26 * HOUR, tz);
+    expect(nextStart - dayStart).toBe(25 * HOUR);
+    const perDay = bucketByDay([work(dayStart, nextStart)], tz);
+    expect(perDay).toHaveLength(1);
+    expect(perDay[0].dayISO).toBe('2026-11-01');
+    expect(perDay[0].activeMs).toBe(25 * HOUR);
+    expect(sumActive(perDay)).toBe(nextStart - dayStart);
+  });
+
+  it('DST spring-forward: a full 23-hour day still balances (§9#14)', () => {
+    // America/New_York starts DST 2026-03-08 (23h day).
+    const tz = 'America/New_York';
+    const dayStart = zonedDayStart(Date.UTC(2026, 2, 8, 12, 0), tz);
+    const nextStart = zonedDayStart(dayStart + 26 * HOUR, tz);
+    expect(nextStart - dayStart).toBe(23 * HOUR);
+    const perDay = bucketByDay([work(dayStart, nextStart)], tz);
+    expect(perDay).toHaveLength(1);
+    expect(perDay[0].activeMs).toBe(23 * HOUR);
+    expect(sumActive(perDay)).toBe(nextStart - dayStart);
+  });
+
+  it('tz changes the day a session lands in but not the total', () => {
+    const start = Date.UTC(2026, 0, 10, 2, 0); // 02:00 UTC
+    const end = Date.UTC(2026, 0, 10, 3, 0);
+    const utc = bucketByDay([work(start, end)], 'UTC');
+    const ny = bucketByDay([work(start, end)], 'America/New_York'); // 21:00 prev day
+    expect(utc[0].dayISO).toBe('2026-01-10');
+    expect(ny[0].dayISO).toBe('2026-01-09');
+    expect(sumActive(utc)).toBe(sumActive(ny));
+  });
+});

apps/server/src/core/page/work-time/bucket-by-day.ts

@@ -0,0 +1,180 @@
+import { WorkSession, PerDay, DayWindow } from './work-time.types';
+
+/**
+ * Merge intervals into a disjoint, sorted union. Overlapping OR touching
+ * intervals are joined. Empty input → [].
+ */
+function union(intervals: Array<[number, number]>): Array<[number, number]> {
+  if (intervals.length === 0) return [];
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
+  const out: Array<[number, number]> = [];
+  let [curStart, curEnd] = sorted[0];
+  for (let i = 1; i < sorted.length; i++) {
+    const [s, e] = sorted[i];
+    if (s <= curEnd) {
+      if (e > curEnd) curEnd = e;
+    } else {
+      out.push([curStart, curEnd]);
+      curStart = s;
+      curEnd = e;
+    }
+  }
+  out.push([curStart, curEnd]);
+  return out;
+}
+
+// Cache one Intl formatter per tz — constructing them is comparatively costly.
+const fmtCache = new Map<string, Intl.DateTimeFormat>();
+
+function partsFmt(tz: string): Intl.DateTimeFormat {
+  let fmt = fmtCache.get(tz);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: false,
+    });
+    fmtCache.set(tz, fmt);
+  }
+  return fmt;
+}
+
+interface WallParts {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/** Wall-clock parts of an instant in `tz` (DST-correct, via Intl). */
+function wallParts(ms: number, tz: string): WallParts {
+  const parts = partsFmt(tz).formatToParts(new Date(ms));
+  const get = (type: string) =>
+    Number(parts.find((p) => p.type === type)?.value ?? '0');
+  let hour = get('hour');
+  // Intl emits "24" for midnight under some engines/locales; normalize to 0.
+  if (hour === 24) hour = 0;
+  return {
+    year: get('year'),
+    month: get('month'),
+    day: get('day'),
+    hour,
+    minute: get('minute'),
+    second: get('second'),
+  };
+}
+
+/** tz offset (wall − real) at an instant, in ms. */
+function offset(ms: number, tz: string): number {
+  const p = wallParts(ms, tz);
+  const asUTC = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+  return asUTC - ms;
+}
+
+/**
+ * Epoch-ms of the local-midnight day start of `ms` in `tz`. DST-correct: takes
+ * the calendar day of the instant, its wall-midnight, then converts back with
+ * the offset that actually applies AT that midnight (refined once). The rare
+ * tz-with-a-DST-transition-exactly-at-midnight case is a documented edge (§9#14).
+ */
+export function zonedDayStart(ms: number, tz: string): number {
+  const p = wallParts(ms, tz);
+  const wallMidnightAsUTC = Date.UTC(p.year, p.month - 1, p.day, 0, 0, 0);
+  let start = wallMidnightAsUTC - offset(ms, tz);
+  // Refine with the offset at the computed midnight (DST may differ from `ms`).
+  start = wallMidnightAsUTC - offset(start, tz);
+  return start;
+}
+
+/** The next local midnight after `dayStart` (handles 23/25h DST days). */
+function nextDayStart(dayStart: number, tz: string): number {
+  // +26h always lands inside the NEXT calendar day (day length ∈ [23h,25h]),
+  // never two days ahead; startOf('day') of it is the next midnight.
+  return zonedDayStart(dayStart + 26 * 60 * 60 * 1000, tz);
+}
+
+function isoDay(dayStart: number, tz: string): string {
+  const p = wallParts(dayStart, tz);
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${p.year}-${pad(p.month)}-${pad(p.day)}`;
+}
+
+/** Clip a union to [lo, hi) and emit windows of `class`. */
+function clip(
+  merged: Array<[number, number]>,
+  lo: number,
+  hi: number,
+  cls: DayWindow['class'],
+): DayWindow[] {
+  const out: DayWindow[] = [];
+  for (const [s, e] of merged) {
+    const start = Math.max(s, lo);
+    const end = Math.min(e, hi);
+    if (end > start) out.push({ start, end, class: cls });
+  }
+  return out;
+}
+
+/**
+ * #395 §6.3 — bucket sessions into calendar days of `tz` for the punch-card.
+ * Pure and deterministic. `work` and `agent_only` are unioned SEPARATELY (else
+ * agent windows would swallow work windows on overlap), then each union is split
+ * at tz midnight boundaries (`startOf('day')` in tz, NOT "+24h" — DST-safe §9#14)
+ * and clipped to each day.
+ *
+ * By construction Σ perDay.activeMs == workMs: the days are a partition of the
+ * `work` union — no loss, no dup, even on 23/25h DST days. `agent_only` windows
+ * are drawn but NOT in activeMs. Empty days between the first and last active day
+ * are emitted (empty track + "—") so the rhythm/pauses stay visible.
+ */
+export function bucketByDay(sessions: WorkSession[], tz: string): PerDay[] {
+  const uWork = union(
+    sessions.filter((s) => s.class === 'work').map((s) => [s.start, s.end]),
+  );
+  const uAgent = union(
+    sessions
+      .filter((s) => s.class === 'agent_only')
+      .map((s) => [s.start, s.end]),
+  );
+
+  if (uWork.length === 0 && uAgent.length === 0) return [];
+
+  const minStart = Math.min(
+    uWork.length ? uWork[0][0] : Infinity,
+    uAgent.length ? uAgent[0][0] : Infinity,
+  );
+  const maxEnd = Math.max(
+    uWork.length ? uWork[uWork.length - 1][1] : -Infinity,
+    uAgent.length ? uAgent[uAgent.length - 1][1] : -Infinity,
+  );
+
+  const perDay: PerDay[] = [];
+  let dayStart = zonedDayStart(minStart, tz);
+  // Guard against a pathological non-advancing boundary.
+  let guard = 0;
+  while (dayStart < maxEnd && guard < 100000) {
+    guard++;
+    const dayEnd = nextDayStart(dayStart, tz);
+    const workWin = clip(uWork, dayStart, dayEnd, 'work');
+    const agentWin = clip(uAgent, dayStart, dayEnd, 'agent_only');
+    const activeMs = workWin.reduce((a, w) => a + (w.end - w.start), 0);
+    const agentMs = agentWin.reduce((a, w) => a + (w.end - w.start), 0);
+    const windows = [...workWin, ...agentWin].sort((a, b) => a.start - b.start);
+    perDay.push({
+      day: dayStart,
+      dayISO: isoDay(dayStart, tz),
+      activeMs,
+      agentMs,
+      windows,
+    });
+    dayStart = dayEnd;
+  }
+  return perDay;
+}

apps/server/src/core/page/work-time/compute-work-time.spec.ts

@@ -0,0 +1,358 @@
+import { computeWorkTime } from './compute-work-time';
+import { bucketByDay } from './bucket-by-day';
+import { TimelineSample, WorkSession } from './work-time.types';
+
+const MIN = 60 * 1000;
+
+/** Union wall-clock of a set of intervals (touching intervals merge). */
+function unionMs(intervals: Array<[number, number]>): number {
+  if (intervals.length === 0) return 0;
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
+  let total = 0;
+  let [cs, ce] = sorted[0];
+  for (let i = 1; i < sorted.length; i++) {
+    const [s, e] = sorted[i];
+    if (s <= ce) {
+      if (e > ce) ce = e;
+    } else {
+      total += ce - cs;
+      cs = s;
+      ce = e;
+    }
+  }
+  return total + (ce - cs);
+}
+
+const ivsOf = (sessions: WorkSession[], cls?: string): Array<[number, number]> =>
+  sessions
+    .filter((x) => cls == null || x.class === cls)
+    .map((x) => [x.start, x.end] as [number, number]);
+
+function s(
+  iso: string,
+  opts: {
+    source?: string | null;
+    chat?: string | null;
+    kind?: string | null;
+    by?: string | null;
+  } = {},
+): TimelineSample {
+  return {
+    createdAt: `${iso}Z`,
+    lastUpdatedById: opts.by ?? 'human-1',
+    lastUpdatedSource: opts.source === undefined ? 'user' : opts.source,
+    lastUpdatedAiChatId: opts.chat ?? null,
+    kind: opts.kind ?? null,
+  };
+}
+
+// §7 config: T_gap=30m, P_in+P_out=10m, P_single=2m.
+const S7 = { tGap: 30 * MIN, agentTGap: 30 * MIN, pIn: 5 * MIN, pOut: 5 * MIN, pSingle: 2 * MIN };
+
+describe('computeWorkTime', () => {
+  it('§7 fixture — sessionizes 20-ish samples to ≈1h32m, not the ≈60h naive span', () => {
+    const rows: TimelineSample[] = [
+      // S1: multi-sample morning session
+      s('2026-07-04T03:40:00'),
+      s('2026-07-04T03:45:00'),
+      s('2026-07-04T03:49:00'),
+      // S2: agent burst (one run) then human supervising → class work
+      s('2026-07-04T15:43:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T15:47:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T15:50:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T16:13:00'),
+      // S3: single
+      s('2026-07-04T18:11:00'),
+      // S4: multi-sample evening session
+      s('2026-07-04T19:38:00'),
+      s('2026-07-04T19:44:00'),
+      s('2026-07-04T19:54:00'),
+      // S5 / S6: two singles two days later, 44m apart → two sessions at T_gap=30
+      s('2026-07-06T15:34:00'),
+      s('2026-07-06T16:18:00'),
+    ];
+
+    const r = computeWorkTime(rows, S7);
+
+    // 19 + 40 + 2 + 26 + 2 + 2 = 91 minutes.
+    expect(r.workMs).toBe(91 * MIN);
+    expect(r.agentOnlyMs).toBe(0);
+    expect(r.sessions).toHaveLength(6);
+    expect(r.sessions.every((x) => x.class === 'work')).toBe(true);
+
+    const naiveSpan =
+      new Date('2026-07-06T16:18:00Z').getTime() -
+      new Date('2026-07-04T03:40:00Z').getTime();
+    expect(naiveSpan).toBeGreaterThan(60 * 60 * MIN); // ≈60h
+    expect(r.workMs).toBeLessThan(naiveSpan / 30); // dramatically smaller
+  });
+
+  it('n=0 → zero, no sessions', () => {
+    const r = computeWorkTime([]);
+    expect(r).toEqual({ workMs: 0, agentOnlyMs: 0, sessions: [] });
+  });
+
+  it('n=1 human → one P_single work session', () => {
+    const r = computeWorkTime([s('2026-07-04T10:00:00')], S7);
+    expect(r.sessions).toHaveLength(1);
+    expect(r.sessions[0].class).toBe('work');
+    expect(r.workMs).toBe(2 * MIN);
+    expect(r.agentOnlyMs).toBe(0);
+    // pre-roll only: [t − P_single, t]
+    expect(r.sessions[0].end).toBe(new Date('2026-07-04T10:00:00Z').getTime());
+  });
+
+  it('n=1 agent → one P_single agent_only session, work=0 (§9#2)', () => {
+    const r = computeWorkTime(
+      [s('2026-07-04T10:00:00', { source: 'agent', chat: 'c1', kind: 'agent' })],
+      S7,
+    );
+    expect(r.sessions).toHaveLength(1);
+    expect(r.sessions[0].class).toBe('agent_only');
+    expect(r.workMs).toBe(0);
+    expect(r.agentOnlyMs).toBe(2 * MIN);
+  });
+
+  it('MUST close the last session — the newest session is not lost (§9#1)', () => {
+    // Two singles a day apart: without the post-loop close, the 2nd is dropped.
+    const rows = [s('2026-07-04T10:00:00'), s('2026-07-05T10:00:00')];
+    const r = computeWorkTime(rows, S7);
+    expect(r.sessions).toHaveLength(2);
+    const lastStart = Math.max(...r.sessions.map((x) => x.start));
+    expect(lastStart).toBe(
+      new Date('2026-07-05T10:00:00Z').getTime() - 2 * MIN,
+    );
+    expect(r.workMs).toBe(4 * MIN);
+  });
+
+  it('agent-burst collapse: density does not inflate — length = wall-clock', () => {
+    const span = ['00', '01', '02', '03', '04', '05', '06'];
+    const dense: TimelineSample[] = span.map((sec) =>
+      s(`2026-07-04T10:00:${sec}`, { source: 'agent', chat: 'c1', kind: 'agent' }),
+    );
+    const sparse: TimelineSample[] = [
+      s('2026-07-04T10:00:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T10:00:06', { source: 'agent', chat: 'c1', kind: 'agent' }),
+    ];
+    const rDense = computeWorkTime(dense, S7);
+    const rSparse = computeWorkTime(sparse, S7);
+    // Same 6-second wall-clock span → same estimate regardless of snapshot count.
+    expect(rDense.agentOnlyMs).toBe(rSparse.agentOnlyMs);
+    expect(rDense.sessions).toHaveLength(1);
+    expect(rDense.sessions[0].class).toBe('agent_only');
+  });
+
+  it('supervisory agent time inside a human session counts as work, not agent', () => {
+    const rows = [
+      s('2026-07-04T10:00:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T10:05:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T10:12:00'), // human within T_gap
+    ];
+    const r = computeWorkTime(rows, S7);
+    expect(r.sessions).toHaveLength(1);
+    expect(r.sessions[0].class).toBe('work');
+    expect(r.agentOnlyMs).toBe(0);
+    expect(r.workMs).toBeGreaterThan(0);
+  });
+
+  it('a DIFFERENT aiChatId breaks the burst — two agent runs, idle gap excluded', () => {
+    // Run c1 ends 10:05, run c2 starts 10:20 (15m > agentTGap 7m) → two sessions.
+    const rows = [
+      s('2026-07-04T10:00:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T10:05:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T10:20:00', { source: 'agent', chat: 'c2', kind: 'agent' }),
+      s('2026-07-04T10:25:00', { source: 'agent', chat: 'c2', kind: 'agent' }),
+    ];
+    const r = computeWorkTime(rows); // default agentTGap = 7m
+    expect(r.sessions).toHaveLength(2);
+    expect(r.sessions.every((x) => x.class === 'agent_only')).toBe(true);
+    // The 15m idle gap between the two runs is NOT counted.
+    const run1 = 5 * MIN + 5 * MIN + 5 * MIN; // pIn + span + pOut
+    expect(r.agentOnlyMs).toBe(2 * run1);
+  });
+
+  it('idle pulse (same/null run) is a full activity sample that continues a burst', () => {
+    const rows = [
+      s('2026-07-04T10:00:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      // idle flush 4m later, null run id → continues the burst, not a new one
+      s('2026-07-04T10:04:00', { source: 'agent', chat: null, kind: 'idle' }),
+      s('2026-07-04T10:08:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+    ];
+    const r = computeWorkTime(rows);
+    expect(r.sessions).toHaveLength(1);
+    // burst span 10:00→10:08 (+pIn/pOut) = 8 + 10 = 18m
+    expect(r.agentOnlyMs).toBe(18 * MIN);
+  });
+
+  it('a USER-sourced idle breaks an agent burst → session is work, not agent_only', () => {
+    // A human supervision idle inherits source=user (aiChatId:null) and must NOT
+    // be swallowed into the agent burst. Δ=3m is within the default agentTGap so
+    // the two samples stay one session — but its class flips to `work`.
+    const rows = [
+      s('2026-07-04T10:00:00', { source: 'agent', chat: 'c1', kind: 'agent' }),
+      s('2026-07-04T10:03:00', { source: 'user', chat: null, kind: 'idle' }),
+    ];
+    const r = computeWorkTime(rows);
+    expect(r.sessions).toHaveLength(1);
+    expect(r.sessions[0].class).toBe('work');
+    expect(r.workMs).toBeGreaterThan(0);
+    // The human idle is NOT captured as agent_only time.
+    expect(r.agentOnlyMs).toBe(0);
+    // Σ over `work` sessions == workMs and Σ over `agent_only` == agentOnlyMs.
+    const sum = (cls: string) =>
+      r.sessions
+        .filter((x) => x.class === cls)
+        .reduce((acc, x) => acc + (x.end - x.start), 0);
+    expect(sum('work')).toBe(r.workMs);
+    expect(sum('agent_only')).toBe(r.agentOnlyMs);
+  });
+
+  it('idle pulse keeps a human writing session visible (not excluded)', () => {
+    const rows = [
+      s('2026-07-04T10:00:00'),
+      s('2026-07-04T10:08:00', { kind: 'idle' }), // pulse within T_gap
+      s('2026-07-04T10:15:00'),
+    ];
+    const r = computeWorkTime(rows);
+    expect(r.sessions).toHaveLength(1);
+    expect(r.sessions[0].class).toBe('work');
+    // span 10:00→10:15 + pIn/pOut = 15 + 10 = 25m
+    expect(r.workMs).toBe(25 * MIN);
+  });
+
+  it('git-source samples are excluded (§10 excludeGit)', () => {
+    const rows = [
+      s('2026-07-04T10:00:00', { source: 'git', kind: 'boundary' }),
+      s('2026-07-04T10:01:00', { source: 'git', kind: 'boundary' }),
+    ];
+    expect(computeWorkTime(rows).workMs).toBe(0);
+    // ...but honoured off:
+    expect(
+      computeWorkTime(rows, { excludeGit: false }).workMs,
+    ).toBeGreaterThan(0);
+  });
+
+  it('rejects an invalid config (tGap < pIn + pOut)', () => {
+    expect(() =>
+      computeWorkTime([s('2026-07-04T10:00:00')], {
+        tGap: 5 * MIN,
+        pIn: 5 * MIN,
+        pOut: 5 * MIN,
+      }),
+    ).toThrow(/tGap/);
+  });
+
+  it('rejects an invalid config (2·agentTGap < pIn + pOut)', () => {
+    // tGap (default 15m) still ≥ pIn+pOut, so only the 2·agentTGap guard trips.
+    // Without it a short session of one class between two of the other could
+    // produce a NON-adjacent cross-class overlap the adjacent-only clip misses.
+    expect(() =>
+      computeWorkTime([s('2026-07-04T10:00:00')], {
+        agentTGap: 2 * MIN,
+        pIn: 5 * MIN,
+        pOut: 5 * MIN,
+      }),
+    ).toThrow(/agentTGap/);
+  });
+
+  // F1 — cross-class double-count. On the DEFAULT config agentTGap (7m) < pIn+pOut
+  // (10m), so a `work` session ending in an agent segment and a nearby separate
+  // `agent_only` run (gap in (7m,10m]) used to produce OVERLAPPING padded
+  // intervals — the same wall-clock counted into BOTH workMs and agentOnlyMs. The
+  // cross-class padding clip must make the two per-class unions disjoint.
+  it('does NOT double-count wall-clock across work/agent_only (§F1)', () => {
+    // user@0s ; agent(chatX)@60s (breaks into a work session with the human) ;
+    // agent(chatY)@560s,590s (a separate agent_only run). Raw gap between the work
+    // session (ends 60s) and the agent run (starts 560s) is 500s ∈ (agentTGap,
+    // pIn+pOut] once padded — the classic overlap window.
+    const rows: TimelineSample[] = [
+      s('2026-07-04T00:00:00'), // user @ 0s
+      s('2026-07-04T00:01:00', { source: 'agent', chat: 'cX', kind: 'agent' }), // @ 60s
+      s('2026-07-04T00:09:20', { source: 'agent', chat: 'cY', kind: 'agent' }), // @ 560s
+      s('2026-07-04T00:09:50', { source: 'agent', chat: 'cY', kind: 'agent' }), // @ 590s
+    ];
+    const r = computeWorkTime(rows); // DEFAULT config
+
+    // Both classes present.
+    expect(r.workMs).toBeGreaterThan(0);
+    expect(r.agentOnlyMs).toBeGreaterThan(0);
+
+    // Per-class metrics are exactly their own union (union, not Σ).
+    expect(r.workMs).toBe(unionMs(ivsOf(r.sessions, 'work')));
+    expect(r.agentOnlyMs).toBe(unionMs(ivsOf(r.sessions, 'agent_only')));
+
+    // The F1 invariant: work-union and agent-union are cross-class-disjoint, so
+    // the union of ALL padded intervals equals workMs + agentOnlyMs (no overlap).
+    // With the clip disabled this fails (union < sum by the 100s overlap).
+    expect(unionMs(ivsOf(r.sessions))).toBe(r.workMs + r.agentOnlyMs);
+  });
+
+  // F1 property/fuzz — random timelines across several timezones must uphold the
+  // work-time invariants. Backs the (corrected) PR claim of a real fuzz test.
+  it('property: random timelines uphold union & cross-class-disjoint invariants', () => {
+    // Deterministic LCG (numerical-recipes constants) so a failure is reproducible.
+    let seed = 0x9e3779b9 >>> 0;
+    const rand = () => {
+      seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+      return seed / 0x100000000;
+    };
+    const pick = <T>(arr: T[]): T => arr[Math.floor(rand() * arr.length)];
+
+    const tzs = [
+      'UTC',
+      'America/New_York',
+      'Europe/Moscow',
+      'Australia/Lord_Howe', // 30-min DST offset — a nasty bucket stress
+    ];
+    const base = Date.UTC(2026, 5, 1, 0, 0, 0); // 2026-06-01Z
+    const chats = ['c1', 'c2', 'c3'];
+
+    for (let iter = 0; iter < 250; iter++) {
+      const tz = pick(tzs);
+      const n = 2 + Math.floor(rand() * 18); // 2..19 rows
+      const rows: TimelineSample[] = [];
+      // Walk time forward by a random inter-sample gap. The gap distribution is
+      // centred on the DANGEROUS band — a bit under to a bit over pIn+pOut (10m)
+      // AND straddling agentTGap (7m) — so adjacent samples routinely split into
+      // separate sessions whose ±P padding would overlap if a class boundary sits
+      // there. Mixing user/agent classes at these gaps reliably manufactures the
+      // work-ending-in-agent → agent_only cross-class boundary F1 is about, plus
+      // dense within-class runs (occasional 0–2m gaps) that exercise the union.
+      let t = base + Math.floor(rand() * 60 * MIN);
+      for (let i = 0; i < n; i++) {
+        const roll = rand();
+        const gap =
+          roll < 0.25
+            ? Math.floor(rand() * 2 * MIN) // dense burst (same-class union)
+            : roll < 0.85
+              ? 5 * MIN + Math.floor(rand() * 8 * MIN) // 5–13m: the split band
+              : 20 * MIN + Math.floor(rand() * 40 * MIN); // long idle → new day-ish
+        t += gap;
+        const iso = new Date(t).toISOString().slice(0, 19); // 'YYYY-MM-DDTHH:MM:SS'
+        const isAgent = rand() < 0.5;
+        rows.push(
+          isAgent
+            ? s(iso, { source: 'agent', chat: pick(chats), kind: 'agent' })
+            : s(iso, { source: 'user', kind: rand() < 0.3 ? 'idle' : 'manual' }),
+        );
+      }
+
+      const r = computeWorkTime(rows); // DEFAULT config
+
+      const workIvs = ivsOf(r.sessions, 'work');
+      const agentIvs = ivsOf(r.sessions, 'agent_only');
+
+      // (1) each metric is exactly its per-class union (catches a union→Σ regress).
+      expect(r.workMs).toBe(unionMs(workIvs));
+      expect(r.agentOnlyMs).toBe(unionMs(agentIvs));
+
+      // (2) NO cross-class overlap: union(all) == workMs + agentOnlyMs (F1).
+      expect(unionMs(ivsOf(r.sessions))).toBe(r.workMs + r.agentOnlyMs);
+
+      // (3) bucket invariant: Σ per-day activeMs == workMs (§6.3).
+      const perDay = bucketByDay(r.sessions, tz);
+      const sumActive = perDay.reduce((a, d) => a + d.activeMs, 0);
+      expect(sumActive).toBe(r.workMs);
+    }
+  });
+});

apps/server/src/core/page/work-time/compute-work-time.ts

@@ -0,0 +1,274 @@
+import {
+  TimelineSample,
+  WorkSession,
+  WorkTimeResult,
+} from './work-time.types';
+import { WorkTimeConfig, resolveWorkTimeConfig } from './work-time.config';
+
+/** A normalized activity sample (one history row), createdAt as epoch-ms. */
+interface NormSample {
+  t: number;
+  isAgent: boolean;
+  aiChatId: string | null;
+  kind: string | null;
+}
+
+/**
+ * A collapsed segment: either a scalar sample (t_start == t_end) or an
+ * agent-burst spanning several agent samples of one run (§5.1). It participates
+ * in sessionization as a single "sample".
+ */
+interface Segment {
+  tStart: number;
+  tEnd: number;
+  isAgent: boolean;
+}
+
+function toMs(v: Date | string | number): number {
+  if (v instanceof Date) return v.getTime();
+  if (typeof v === 'number') return v;
+  return new Date(v).getTime();
+}
+
+/**
+ * Normalize raw rows → sorted, deduped activity samples. `git` is dropped when
+ * configured; every other kind (incl. `idle` — the continuous-work pulse §3) is
+ * a real activity sample. Sort is by createdAt ASC; samples whose timestamps
+ * fall in the same `dedupRoundMs` bucket collapse to one (§9#7: a synchronous
+ * boundary row + the immediate agent snapshot can share a createdAt). A merged
+ * sample is human unless EVERY member is an agent, so supervision never gets
+ * mis-attributed to the agent.
+ */
+function normalize(
+  rows: TimelineSample[],
+  config: WorkTimeConfig,
+): NormSample[] {
+  const samples: NormSample[] = [];
+  for (const row of rows) {
+    const source = row.lastUpdatedSource;
+    if (config.excludeGit && source === 'git') continue;
+    samples.push({
+      t: toMs(row.createdAt),
+      isAgent: source === 'agent',
+      aiChatId: row.lastUpdatedAiChatId ?? null,
+      kind: row.kind ?? null,
+    });
+  }
+  samples.sort((a, b) => a.t - b.t);
+
+  if (config.dedupRoundMs <= 0 || samples.length < 2) return samples;
+
+  const deduped: NormSample[] = [];
+  for (const s of samples) {
+    const prev = deduped[deduped.length - 1];
+    if (prev && s.t - prev.t < config.dedupRoundMs) {
+      // Merge into the previous sample. Human wins the class; keep the earliest
+      // t; keep a non-null aiChatId if either has one (so a bare boundary row
+      // does not erase the run id).
+      prev.isAgent = prev.isAgent && s.isAgent;
+      prev.aiChatId = prev.aiChatId ?? s.aiChatId;
+      // Prefer the more specific kind (a real kind over a null/boundary) only
+      // matters for burst continuation; keep prev.kind (earliest) as-is.
+      continue;
+    }
+    deduped.push({ ...s });
+  }
+  return deduped;
+}
+
+/**
+ * Collapse consecutive same-run agent samples into one burst segment (§5.1) so a
+ * dense burst (8 snapshots in 7 minutes) contributes its wall-clock, not a count
+ * × block. A burst is broken by any sample NOT continuing the same aiChatId
+ * agent run: a non-agent sample, a `boundary` (actor transition), or a DIFFERENT
+ * aiChatId. Only an AGENT-sourced `idle` pulse with the SAME or a null aiChatId
+ * continues the burst (its label lags the real edit ≤ maxWait, well within
+ * rounding); a user-sourced `idle` (a human supervision pulse) breaks it.
+ */
+function collapse(samples: NormSample[], config: WorkTimeConfig): Segment[] {
+  const segments: Segment[] = [];
+  let burst: { chatId: string | null; tStart: number; tEnd: number } | null =
+    null;
+
+  const flush = () => {
+    if (!burst) return;
+    let tEnd = burst.tEnd;
+    if (config.burstCapMs != null && tEnd - burst.tStart > config.burstCapMs) {
+      tEnd = burst.tStart + config.burstCapMs;
+    }
+    segments.push({ tStart: burst.tStart, tEnd, isAgent: true });
+    burst = null;
+  };
+
+  for (const s of samples) {
+    // An agent-sourced idle pulse continues the current agent burst (same or
+    // null run id). A user-sourced idle (human supervision) must NOT be swallowed
+    // here — it falls through to the human branch so the session flips to `work`.
+    if (
+      burst &&
+      s.kind === 'idle' &&
+      s.isAgent &&
+      (s.aiChatId === burst.chatId || s.aiChatId == null)
+    ) {
+      burst.tEnd = s.t;
+      continue;
+    }
+    if (s.isAgent && s.kind !== 'boundary') {
+      if (burst && burst.chatId === s.aiChatId) {
+        burst.tEnd = s.t;
+      } else {
+        flush();
+        burst = { chatId: s.aiChatId, tStart: s.t, tEnd: s.t };
+      }
+      continue;
+    }
+    // A human sample, a boundary, or an agent-boundary: breaks the burst and is
+    // itself a zero-width segment (its class follows its own source).
+    flush();
+    segments.push({ tStart: s.t, tEnd: s.t, isAgent: s.isAgent });
+  }
+  flush();
+  return segments;
+}
+
+function gapThreshold(
+  a: Segment,
+  b: Segment,
+  config: WorkTimeConfig,
+): number {
+  return a.isAgent && b.isAgent ? config.agentTGap : config.tGap;
+}
+
+/** Merge intervals; overlapping OR touching intervals are unioned. */
+function unionDuration(intervals: Array<[number, number]>): number {
+  if (intervals.length === 0) return 0;
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
+  let total = 0;
+  let [curStart, curEnd] = sorted[0];
+  for (let i = 1; i < sorted.length; i++) {
+    const [s, e] = sorted[i];
+    if (s <= curEnd) {
+      if (e > curEnd) curEnd = e;
+    } else {
+      total += curEnd - curStart;
+      curStart = s;
+      curEnd = e;
+    }
+  }
+  total += curEnd - curStart;
+  return total;
+}
+
+/**
+ * #395 core — estimate time worked on a page from its history timeline (§5).
+ * Pure and deterministic: no DB, no clock, no I/O.
+ *
+ * Pipeline: normalize+dedup → collapse agent bursts → ONE sessionization pass
+ * over all segments (threshold depends on the pair: both-agent → agentTGap, else
+ * tGap; the last session is ALWAYS closed after the loop) → class per finished
+ * session (all-agent → agent_only, else work) → pad each session (multi-sample
+ * → [first−P_in, last+P_out]; lone scalar → [t−P_single, t]) → clip padding of
+ * adjacent DIFFERENT-class sessions at the raw-gap midpoint (so work/agent_only
+ * never overlap) → metrics are the union wall-clock within each class (union, not
+ * Σ, so overlaps never double, and cross-class-disjoint by the clip above).
+ */
+export function computeWorkTime(
+  rows: TimelineSample[],
+  config?: Partial<WorkTimeConfig>,
+): WorkTimeResult {
+  const cfg = resolveWorkTimeConfig(config);
+  const samples = normalize(rows, cfg);
+  const segments = collapse(samples, cfg);
+
+  // Sessionize — one pass over ALL segments.
+  const rawSessions: Segment[][] = [];
+  let cur: Segment[] | null = null;
+  for (const seg of segments) {
+    if (cur == null) {
+      cur = [seg];
+    } else {
+      const last = cur[cur.length - 1];
+      if (seg.tStart - last.tEnd <= gapThreshold(last, seg, cfg)) {
+        cur.push(seg);
+      } else {
+        rawSessions.push(cur);
+        cur = [seg];
+      }
+    }
+  }
+  if (cur != null) rawSessions.push(cur); // MUST close the last session (§5, §9#1)
+
+  // A finished session with BOTH its raw (unpadded) span and its padded bounds.
+  // `rawSessions` are already in ascending time order, so `built` is too.
+  interface BuiltSession {
+    rawStart: number;
+    rawEnd: number;
+    padStart: number;
+    padEnd: number;
+    cls: WorkSession['class'];
+  }
+  const built: BuiltSession[] = [];
+
+  for (const segs of rawSessions) {
+    const first = segs[0];
+    const last = segs[segs.length - 1];
+    const cls = segs.every((s) => s.isAgent) ? 'agent_only' : 'work';
+
+    let padStart: number;
+    let padEnd: number;
+    if (segs.length === 1 && first.tStart === first.tEnd) {
+      // Lone single-instant session (one scalar, or a one-snapshot agent run):
+      // pre-roll only, no invented "future" work (§5).
+      padStart = first.tStart - cfg.pSingle;
+      padEnd = first.tStart;
+    } else {
+      padStart = first.tStart - cfg.pIn;
+      padEnd = last.tEnd + cfg.pOut;
+    }
+
+    built.push({
+      rawStart: first.tStart,
+      rawEnd: last.tEnd,
+      padStart,
+      padEnd,
+      cls,
+    });
+  }
+
+  // Clip cross-class padding so a `work` and an `agent_only` session that abut
+  // never claim the same wall-clock. For each ADJACENT pair of DIFFERENT classes,
+  // cap the earlier session's trailing pad and the later session's leading pad at
+  // the MIDPOINT of the raw (unpadded) inactivity gap between them: the earlier
+  // padded interval then ends ≤ midpoint and the later one starts ≥ midpoint, so
+  // the two are disjoint (they touch at most at the midpoint). This makes the
+  // per-class unions (workMs / agentOnlyMs) cross-class-disjoint BY CONSTRUCTION
+  // — closing the double-count where a work session ending in an agent segment
+  // and a nearby agent_only session (gap in (agentTGap, pIn+pOut]) overlapped and
+  // were counted into both metrics (§5, §9). Within-class adjacency is left
+  // untouched: `unionDuration` already dedups it, and clipping there could perturb
+  // the per-class metric value.
+  for (let i = 1; i < built.length; i++) {
+    const a = built[i - 1];
+    const b = built[i];
+    if (a.cls === b.cls) continue;
+    const midpoint = (a.rawEnd + b.rawStart) / 2;
+    if (a.padEnd > midpoint) a.padEnd = midpoint;
+    if (b.padStart < midpoint) b.padStart = midpoint;
+  }
+
+  const sessions: WorkSession[] = [];
+  const workIvs: Array<[number, number]> = [];
+  const agentIvs: Array<[number, number]> = [];
+  for (const s of built) {
+    sessions.push({ start: s.padStart, end: s.padEnd, class: s.cls });
+    (s.cls === 'work' ? workIvs : agentIvs).push([s.padStart, s.padEnd]);
+  }
+
+  sessions.sort((a, b) => a.start - b.start);
+
+  return {
+    workMs: unionDuration(workIvs),
+    agentOnlyMs: unionDuration(agentIvs),
+    sessions,
+  };
+}

apps/server/src/core/page/work-time/index.ts

@@ -0,0 +1,15 @@
+export { computeWorkTime } from './compute-work-time';
+export { bucketByDay, zonedDayStart } from './bucket-by-day';
+export {
+  DEFAULT_WORK_TIME_CONFIG,
+  resolveWorkTimeConfig,
+} from './work-time.config';
+export type { WorkTimeConfig } from './work-time.config';
+export type {
+  TimelineSample,
+  WorkSession,
+  WorkTimeResult,
+  SessionClass,
+  DayWindow,
+  PerDay,
+} from './work-time.types';

apps/server/src/core/page/work-time/work-time.config.ts

@@ -0,0 +1,102 @@
+import {
+  IDLE_MAX_WAIT_USER,
+  IDLE_MAX_WAIT_AGENT,
+} from '../../../collaboration/constants';
+
+/**
+ * #395 — tunables for the work-time estimate (§10). Defaults are calibrated off
+ * #374's idle-pulse ceilings: after #374 a continuous editing session leaves a
+ * history row at least every ~IDLE_MAX_WAIT (10m user / 5m agent), so a gap
+ * WIDER than that ceiling contains un-pulsed idle time = (partial) inactivity.
+ * `tGap` therefore sits a little above the user ceiling, `agentTGap` a little
+ * above the agent ceiling — a gap within the threshold is pulse-backed and
+ * counts as work.
+ */
+export interface WorkTimeConfig {
+  /** user inactivity timeout: gap ≤ tGap between samples = continuous work. */
+  tGap: number;
+  /** timeout for a pair of consecutive agent samples (tighter than tGap). */
+  agentTGap: number;
+  /** pre-roll padding for a multi-sample session (work began before sample 1). */
+  pIn: number;
+  /** post-roll padding for a multi-sample session (work continued after last). */
+  pOut: number;
+  /** block for a lone single-sample session (pre-roll only, no invented future). */
+  pSingle: number;
+  /** drop `git`-source samples (they are not human/agent article work). */
+  excludeGit: boolean;
+  /** optional cap on one collapsed agent-burst segment's wall-clock (§9#3). */
+  burstCapMs?: number;
+  /** samples whose createdAt round to the same bucket dedup to one (§9#7). */
+  dedupRoundMs: number;
+}
+
+export const DEFAULT_WORK_TIME_CONFIG: WorkTimeConfig = {
+  // ~15m: IDLE_MAX_WAIT_USER (10m) + headroom. Empirically backcast on a real
+  // 307-snapshot article (≈24h at 15m matched the owner's estimate; 30/45m
+  // over-counted). See #395 §10.
+  tGap: 15 * 60 * 1000,
+  // ~7m: IDLE_MAX_WAIT_AGENT (5m) + headroom.
+  agentTGap: 7 * 60 * 1000,
+  pIn: 5 * 60 * 1000,
+  pOut: 5 * 60 * 1000,
+  pSingle: 2 * 60 * 1000,
+  excludeGit: true,
+  burstCapMs: undefined,
+  dedupRoundMs: 1000,
+};
+
+// Compile-time cross-check that the defaults really are pulse-anchored — if a
+// future edit moves the #374 ceilings, this reminds us to re-calibrate.
+void IDLE_MAX_WAIT_USER;
+void IDLE_MAX_WAIT_AGENT;
+
+/**
+ * Fill a partial config with defaults and validate it. Cross-class metric
+ * disjointness is guaranteed jointly by `computeWorkTime`'s adjacent-pair padding
+ * clip (it caps the padding of adjacent DIFFERENT-class sessions at the raw-gap
+ * midpoint) AND the two bounds enforced below (§5):
+ *   - `tGap ≥ pIn + pOut`: a session's own padding never exceeds its inactivity
+ *     window.
+ *   - `2·agentTGap ≥ pIn + pOut`: makes the adjacent-only clip provably COMPLETE.
+ *     A NON-adjacent (i, i+2) cross-class overlap could only arise from two
+ *     same-class sessions separated by a full intervening session of the other
+ *     class; that separation spans at least two inter-session gaps, each strictly
+ *     `> agentTGap`, so it is `> 2·agentTGap`. Requiring `2·agentTGap ≥ pIn + pOut`
+ *     means even the widest padded reach (pIn + pOut) cannot bridge it — so the
+ *     only cross-class overlaps possible are between ADJACENT sessions, which the
+ *     clip handles. `workMs`/`agentOnlyMs` are therefore disjoint by construction.
+ */
+export function resolveWorkTimeConfig(
+  partial?: Partial<WorkTimeConfig>,
+): WorkTimeConfig {
+  const config = { ...DEFAULT_WORK_TIME_CONFIG, ...(partial ?? {}) };
+
+  for (const key of [
+    'tGap',
+    'agentTGap',
+    'pIn',
+    'pOut',
+    'pSingle',
+    'dedupRoundMs',
+  ] as const) {
+    const value = config[key];
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`work-time config: ${key} must be a non-negative number`);
+    }
+  }
+  if (config.burstCapMs != null && config.burstCapMs <= 0) {
+    throw new Error('work-time config: burstCapMs must be > 0 when set');
+  }
+  if (config.tGap < config.pIn + config.pOut) {
+    throw new Error(
+      "work-time config: tGap must be ≥ pIn + pOut (a session's padding may not exceed its inactivity window)",
+    );
+  }
+  if (2 * config.agentTGap < config.pIn + config.pOut) {
+    throw new Error(
+      'work-time config: 2·agentTGap must be ≥ pIn + pOut (so non-adjacent cross-class padding cannot overlap)',
+    );
+  }
+  return config;
+}

apps/server/src/core/page/work-time/work-time.types.ts

@@ -0,0 +1,73 @@
+/**
+ * #395 — "time worked on an article" domain types.
+ *
+ * The estimate is built by sessionizing a page's `page_history` timeline on
+ * inactivity gaps (WakaTime-style), NOT by taking the span between the first and
+ * last edit (which over-counts sleep / lunch / idle days). See the design doc in
+ * issue #395 §5–§6.3 for the normative algorithm.
+ */
+
+/**
+ * A single `page_history` row projected for the work-time computation — the
+ * cheap columns only (no `content`). Produced by
+ * `PageHistoryRepo.findTimelineByPageId`. `createdAt` is whatever the DB driver
+ * hands back (Date); the pure core normalizes it to epoch-ms itself so it stays
+ * deterministic and DB-free.
+ */
+export interface TimelineSample {
+  createdAt: Date | string | number;
+  lastUpdatedById: string | null;
+  /** 'user' | 'agent' | 'git' | null (legacy autosave = human). */
+  lastUpdatedSource: string | null;
+  lastUpdatedAiChatId: string | null;
+  /** #370 tier: 'manual' | 'agent' | 'idle' | 'boundary' | null (legacy). */
+  kind: string | null;
+}
+
+/** A finished session's class (§5.1). */
+export type SessionClass = 'work' | 'agent_only';
+
+/**
+ * A finished session: absolute wall-clock bounds already padded with P_in/P_out
+ * (multi-sample) or P_single (single scalar), plus its class. This is enough for
+ * both the metrics and the per-day punch-card colouring.
+ */
+export interface WorkSession {
+  /** epoch-ms, inclusive lower bound (already P-padded). */
+  start: number;
+  /** epoch-ms, exclusive upper bound (already P-padded). */
+  end: number;
+  class: SessionClass;
+}
+
+/** Output of {@link computeWorkTime}. */
+export interface WorkTimeResult {
+  /** union wall-clock of `work` sessions, ms (the headline metric). */
+  workMs: number;
+  /** union wall-clock of `agent_only` sessions, ms (secondary). */
+  agentOnlyMs: number;
+  sessions: WorkSession[];
+}
+
+/** One activity window inside a calendar day (already clipped to the day). */
+export interface DayWindow {
+  /** epoch-ms. */
+  start: number;
+  /** epoch-ms. */
+  end: number;
+  class: SessionClass;
+}
+
+/** One calendar day of the punch-card (§6.3). */
+export interface PerDay {
+  /** epoch-ms of the local-midnight day start in the requested tz. */
+  day: number;
+  /** 'YYYY-MM-DD' in the requested tz — stable, tz-independent label. */
+  dayISO: string;
+  /** Σ of `work` windows this day, ms. Σ over days == workMs (invariant §6.3). */
+  activeMs: number;
+  /** Σ of `agent_only` windows this day, ms (drawn, NOT in activeMs). */
+  agentMs: number;
+  /** both classes, clipped to the day, sorted by start (for drawing). */
+  windows: DayWindow[];
+}

apps/server/src/database/database.module.ts

@@ -37,6 +37,7 @@ import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider
 import { AiMcpServerRepo } from '@docmost/db/repos/ai-chat/ai-mcp-server.repo';
 import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
 import { PageEmbeddingRepo } from '@docmost/db/repos/ai-chat/page-embedding.repo';
+import { ApiKeyRepo } from '@docmost/db/repos/api-key/api-key.repo';
 import { PageListener } from '@docmost/db/listeners/page.listener';
 import { PostgresJSDialect } from 'kysely-postgres-js';
 import * as postgres from 'postgres';
@@ -129,6 +130,7 @@ import { firstSqlToken } from '../integrations/metrics/metrics.constants';
     AiMcpServerRepo,
     AiAgentRoleRepo,
     PageEmbeddingRepo,
+    ApiKeyRepo,
     PageListener,
   ],
   exports: [
@@ -164,6 +166,7 @@ import { firstSqlToken } from '../integrations/metrics/metrics.constants';
     AiMcpServerRepo,
     AiAgentRoleRepo,
     PageEmbeddingRepo,
+    ApiKeyRepo,
   ],
 })
 export class DatabaseModule implements OnApplicationBootstrap {

apps/server/src/database/repos/api-key/api-key.repo.ts

@@ -0,0 +1,110 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { DB, Users } from '@docmost/db/types/db';
+import { dbOrTx } from '@docmost/db/utils';
+import { ApiKey, InsertableApiKey } from '@docmost/db/types/entity.types';
+import { jsonObjectFrom } from 'kysely/helpers/postgres';
+import { ExpressionBuilder } from 'kysely';
+
+// Public-facing shape: the api_keys row plus a compact creator attribution used
+// by the admin list (the workspace-wide view attributes each key to its author).
+export type ApiKeyWithCreator = ApiKey & {
+  creator: Pick<Users, 'id' | 'name' | 'email' | 'avatarUrl'> | null;
+};
+
+@Injectable()
+export class ApiKeyRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  // Compact creator attribution embedded in the admin list rows. A nested
+  // subquery (jsonObjectFrom) keeps it one round-trip; the token material is
+  // never stored, so nothing sensitive is joined in.
+  private withCreator(eb: ExpressionBuilder<DB, 'apiKeys'>) {
+    return jsonObjectFrom(
+      eb
+        .selectFrom('users')
+        .select(['users.id', 'users.name', 'users.email', 'users.avatarUrl'])
+        .whereRef('users.id', '=', 'apiKeys.creatorId'),
+    ).as('creator');
+  }
+
+  async findById(
+    id: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<ApiKey | undefined> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('apiKeys')
+      .selectAll()
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      // Convention (soft-delete): a revoked key is invisible to reads.
+      .where('deletedAt', 'is', null)
+      .executeTakeFirst();
+  }
+
+  async findByCreator(
+    creatorId: string,
+    workspaceId: string,
+  ): Promise<ApiKeyWithCreator[]> {
+    return this.db
+      .selectFrom('apiKeys')
+      .selectAll('apiKeys')
+      .select((eb) => this.withCreator(eb))
+      .where('creatorId', '=', creatorId)
+      .where('workspaceId', '=', workspaceId)
+      .where('deletedAt', 'is', null)
+      .orderBy('createdAt', 'desc')
+      .execute() as unknown as Promise<ApiKeyWithCreator[]>;
+  }
+
+  async findAllInWorkspace(
+    workspaceId: string,
+  ): Promise<ApiKeyWithCreator[]> {
+    return this.db
+      .selectFrom('apiKeys')
+      .selectAll('apiKeys')
+      .select((eb) => this.withCreator(eb))
+      .where('workspaceId', '=', workspaceId)
+      .where('deletedAt', 'is', null)
+      .orderBy('createdAt', 'desc')
+      .execute() as unknown as Promise<ApiKeyWithCreator[]>;
+  }
+
+  async insert(
+    insertable: InsertableApiKey,
+    trx?: KyselyTransaction,
+  ): Promise<ApiKey> {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .insertInto('apiKeys')
+      .values(insertable)
+      .returningAll()
+      .executeTakeFirst();
+  }
+
+  // Soft-delete = revoke. Terminal: the row stays for forensics but is invisible
+  // to every read above, so validate() denies it immediately (no grace window).
+  async softDelete(id: string, workspaceId: string): Promise<void> {
+    await this.db
+      .updateTable('apiKeys')
+      .set({ deletedAt: new Date(), updatedAt: new Date() })
+      .where('id', '=', id)
+      .where('workspaceId', '=', workspaceId)
+      .where('deletedAt', 'is', null)
+      .execute();
+  }
+
+  // Throttled best-effort forensics stamp. Not on the critical path: callers
+  // fire-and-forget and swallow errors, so it never fails a request.
+  async touchLastUsed(id: string): Promise<void> {
+    await this.db
+      .updateTable('apiKeys')
+      .set({ lastUsedAt: new Date() })
+      .where('id', '=', id)
+      .where('deletedAt', 'is', null)
+      .execute();
+  }
+}

apps/server/src/database/repos/page/page-history.repo.ts

@@ -157,6 +157,44 @@ export class PageHistoryRepo {
     return { ...result, items: result.items.map(attachPageHistoryAgent) };
   }
 
+  /**
+   * #395 — cheap projection of a page's FULL history timeline for the work-time
+   * estimate: only the columns the sessionizer needs, no heavy `content`, sorted
+   * oldest→newest. The secondary `id` tie-break keeps rows sharing a `createdAt`
+   * (e.g. a synchronous pre-agent boundary row + the immediate agent snapshot)
+   * in a deterministic order.
+   */
+  async findTimelineByPageId(
+    pageId: string,
+    trx?: KyselyTransaction,
+  ): Promise<
+    Array<
+      Pick<
+        PageHistory,
+        | 'createdAt'
+        | 'lastUpdatedById'
+        | 'lastUpdatedSource'
+        | 'lastUpdatedAiChatId'
+        | 'kind'
+      >
+    >
+  > {
+    const db = dbOrTx(this.db, trx);
+    return db
+      .selectFrom('pageHistory')
+      .select([
+        'createdAt',
+        'lastUpdatedById',
+        'lastUpdatedSource',
+        'lastUpdatedAiChatId',
+        'kind',
+      ])
+      .where('pageId', '=', pageId)
+      .orderBy('createdAt', 'asc')
+      .orderBy('id', 'asc')
+      .execute();
+  }
+
   async findPageLastHistory(
     pageId: string,
     opts?: {

apps/server/src/integrations/environment/environment.service.ts

@@ -70,6 +70,23 @@ export class EnvironmentService {
     return this.configService.get<string>('JWT_TOKEN_EXPIRES_IN', '90d');
   }
 
+  // Kill-switch for the agent API-key feature. Default ON (unset -> enabled): a
+  // deploy that never sets the variable must NOT silently kill every agent. The
+  // parse is STRICT — the value is validated by environment.validation to be
+  // exactly 'true' or 'false' (or absent), so a typo like `=0`/`=off`/`=False`
+  // fails at boot rather than being read as "enabled" (which would leave an
+  // operator who yanked the switch during an incident with it still on). When
+  // OFF: validate() denies every api-key token and the issuance endpoints 404.
+  isApiKeysEnabled(): boolean {
+    return this.configService.get<string>('API_KEYS_ENABLED', 'true') !== 'false';
+  }
+
+  // Raw value (or undefined) for the boot log, so the state after each deploy is
+  // verifiable in container logs: `API keys: ENABLED/DISABLED (API_KEYS_ENABLED=...)`.
+  getApiKeysEnabledRaw(): string | undefined {
+    return this.configService.get<string>('API_KEYS_ENABLED');
+  }
+
   getCookieExpiresIn(): Date {
     const expiresInStr = this.getJwtTokenExpiresIn();
     let msUntilExpiry: number;

apps/server/src/integrations/environment/environment.validation.ts

@@ -103,6 +103,15 @@ export class EnvironmentVariables {
   @IsString()
   TYPESENSE_LOCALE: string;
 
+  // Agent API-key kill-switch. Optional (absent -> default ON). STRICT: only the
+  // literals 'true'/'false' are accepted, so `=0`/`=off`/`=False` fail at boot
+  // instead of being silently read as "enabled" — the switch must actually flip
+  // when an operator flips it. See EnvironmentService.isApiKeysEnabled.
+  @IsOptional()
+  @IsIn(['true', 'false'])
+  @IsString()
+  API_KEYS_ENABLED: string;
+
   @IsOptional()
   @ValidateIf((obj) => obj.AI_DRIVER)
   @IsIn(['openai', 'openai-compatible', 'gemini', 'ollama'])

apps/server/src/integrations/import/services/import-attachment.service.drawio-svg.spec.ts

@@ -0,0 +1,131 @@
+// p-limit and @sindresorhus/slugify are ESM-only and not in jest's transform
+// allowlist; both are irrelevant to createDrawioSvg (a pure fs + string method),
+// so they are mocked out to keep the module graph loadable under ts-jest.
+jest.mock('p-limit', () => ({
+  __esModule: true,
+  default: () => (fn: () => unknown) => fn(),
+}));
+jest.mock('@sindresorhus/slugify', () => ({
+  __esModule: true,
+  default: (input: string) => String(input),
+}));
+
+import { promises as fs } from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ImportAttachmentService } from './import-attachment.service';
+
+/**
+ * Unit test for ImportAttachmentService.createDrawioSvg (issue #507).
+ *
+ * The Confluence import wraps a `.drawio` file into a `.drawio.svg` attachment.
+ * The `content=` payload MUST be the mxfile XML entity-escaped (draw.io's native
+ * form), NOT base64 — draw.io's editor decodes a base64 content= via Latin-1
+ * atob, mangling every non-ASCII char into mojibake. createDrawioSvg touches no
+ * injected dependency, so the service is built with placeholder deps.
+ */
+describe('ImportAttachmentService.createDrawioSvg (#507)', () => {
+  const service = new ImportAttachmentService(
+    {} as any,
+    {} as any,
+    {} as any,
+  );
+  const call = (p: string): Promise<Buffer> =>
+    (service as any).createDrawioSvg(p);
+
+  let tmpDir: string;
+  beforeAll(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'drawio-507-'));
+  });
+  afterAll(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  const writeDrawio = async (name: string, xml: string): Promise<string> => {
+    const p = path.join(tmpDir, name);
+    await fs.writeFile(p, xml, 'utf-8');
+    return p;
+  };
+
+  it('writes content= as entity-encoded XML, not base64', async () => {
+    const drawio =
+      '<mxfile host="Confluence"><diagram name="Схема — ёж">' +
+      '<mxGraphModel><root><mxCell id="0"/>' +
+      '<mxCell id="2" value="Старт-бит" vertex="1" parent="0"/>' +
+      '</root></mxGraphModel></diagram></mxfile>';
+    const p = await writeDrawio('cyrillic.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+
+    // Entity-encoded XML form, starting with &lt;mxfile — never a base64 blob.
+    expect(content).toMatch(/^&lt;mxfile/);
+    expect(content).toContain('&lt;');
+    // Non-ASCII survives as raw UTF-8, with no Latin-1 mojibake.
+    expect(content).toContain('Старт-бит');
+    expect(content).toContain('Схема — ёж');
+    expect(content).not.toContain('Ð');
+
+    // Decoding the attribute (un-escaping) yields the original drawio file.
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+
+  it('encodes literal tab/newline/CR as numeric char-refs, not literal control chars (#507 F1)', async () => {
+    // A literal tab/newline/CR inside the mxfile XML would be collapsed to a
+    // single space by XML attribute-value normalization when the draw.io editor
+    // reads content=, silently flattening multi-line labels and tab-bearing
+    // values. They must be emitted as numeric char-refs instead.
+    const drawio =
+      '<mxfile><diagram name="p">' +
+      '<mxGraphModel><root><mxCell id="0"/>' +
+      '<mxCell id="2" value="col1\tcol2" style="html=1;\nshadow=0" vertex="1" parent="0"/>' +
+      '<mxCell id="3" value="Line1\nLine2\rLine3" vertex="1" parent="0"/>' +
+      '</root></mxGraphModel></diagram></mxfile>';
+    const p = await writeDrawio('ctrl.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+    // No literal control chars survive in the attribute value.
+    expect(content).not.toMatch(/[\t\n\r]/);
+    // They round-trip as numeric char-refs.
+    expect(content).toContain('&#x9;');
+    expect(content).toContain('&#xa;');
+    expect(content).toContain('&#xd;');
+    // Decoding (char-refs back to literal, entities back) recovers the file.
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&#x9;/gi, '\t')
+      .replace(/&#xa;/gi, '\n')
+      .replace(/&#xd;/gi, '\r')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+
+  it('escapes XML metacharacters in the drawio payload', async () => {
+    const drawio = '<mxfile><diagram name="a &amp; b">"q" &lt;x&gt;</diagram></mxfile>';
+    const p = await writeDrawio('meta.drawio', drawio);
+
+    const svg = (await call(p)).toString('utf-8');
+    const content = /content="([^"]*)"/.exec(svg)?.[1];
+    expect(content).toBeDefined();
+    // The attribute value must contain no bare `<`, `>` or `"` that would break
+    // out of the content="..." attribute or the SVG element.
+    expect(content).not.toMatch(/[<>"]/);
+    const decoded = content!
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, '&');
+    expect(decoded).toBe(drawio);
+  });
+});

apps/server/src/integrations/import/services/import-attachment.service.ts

@@ -8,6 +8,7 @@ import { createReadStream } from 'node:fs';
 import { promises as fs } from 'fs';
 import { Readable } from 'stream';
 import { getMimeType, sanitizeFileName } from '../../../common/helpers';
+import { htmlEscape } from '../../../common/helpers/html-escaper';
 import { v7 } from 'uuid';
 import { FileTask } from '@docmost/db/types/entity.types';
 import { getAttachmentFolderPath } from '../../../core/attachment/attachment.utils';
@@ -849,7 +850,12 @@ export class ImportAttachmentService {
   ): Promise<Buffer> {
     try {
       const drawioContent = await fs.readFile(drawioPath, 'utf-8');
-      const drawioBase64 = Buffer.from(drawioContent).toString('base64');
+      // Write the mxfile XML XML-entity-escaped (draw.io's native content= form),
+      // NOT base64. draw.io's editor decodes a base64 content= via Latin-1 atob
+      // (no UTF-8 step), turning every non-ASCII char (Cyrillic, ё, —) into
+      // mojibake; the entity-encoded form is decoded by the DOM as UTF-8 and
+      // opens intact. Docmost's own decoder reads both forms.
+      const drawioEscaped = this.xmlEscapeContent(drawioContent);
 
       let imageElement = '';
       // If we have a PNG, include it in the SVG
@@ -875,7 +881,7 @@ export class ImportAttachmentService {
       width="600"
       height="400"
       viewBox="0 0 600 400"
-      content="${drawioBase64}">${imageElement}</svg>`;
+      content="${drawioEscaped}">${imageElement}</svg>`;
 
       return Buffer.from(svgContent, 'utf-8');
     } catch (error) {
@@ -884,6 +890,24 @@ export class ImportAttachmentService {
     }
   }
 
+  /**
+   * Escape a string so it is safe as the value of a double-quoted XML attribute
+   * (the `content=` payload of a `.drawio.svg`). The shared `htmlEscape` covers
+   * `& < > " '` (a strict superset of what this attribute needs; the extra `'`
+   * escape is harmless in a `"`-delimited value). On top of that, the numeric
+   * char-refs for tab/newline/CR are required: a literal tab/newline/CR inside
+   * an attribute value is collapsed to a single space by XML attribute-value
+   * normalization on DOM read (both our decoder and the real draw.io editor),
+   * silently flattening multi-line labels and tab-bearing values. Char-refs
+   * survive that normalization (#507).
+   */
+  private xmlEscapeContent(s: string): string {
+    return htmlEscape(s)
+      .replace(/\t/g, '&#x9;')
+      .replace(/\n/g, '&#xa;')
+      .replace(/\r/g, '&#xd;');
+  }
+
   private async uploadWithRetry(opts: {
     abs: string;
     storageFilePath: string;

apps/server/src/integrations/mcp/mcp-auth.helpers.ts

@@ -304,37 +304,102 @@ export function clientIp(req: ClientIpRequest): string {
   return 'unknown';
 }
 
-// Minimal structural shape of the TokenService.verifyJwt method we depend on,
-// so this module never imports the concrete TokenService (heavy graph).
-export interface AccessJwtVerifier {
-  verifyJwt: (
-    token: string,
-    type: JwtType,
-  ) => Promise<{
-    sub?: string;
-    email?: string;
-    workspaceId?: string;
-    sessionId?: string;
-  }>;
-}
-
-/**
- * Bind a TokenService-like verifier into a one-arg `verifyJwt(token)` that
- * ALWAYS enforces `JwtType.ACCESS`. This is the single place where the /mcp
- * Bearer path pins the token type: a Bearer access token must be verified AS an
- * access token (not refresh/exchange/collab/etc.), so the type literal is fixed
- * here rather than at the call site. McpService.verifyMcpBearer delegates to
- * this, keeping the `JwtType.ACCESS` choice testable without the heavy graph.
- */
-export function bindAccessJwtVerifier(
-  tokenService: AccessJwtVerifier,
-): (token: string) => Promise<{
+// The decoded payload shared by the /mcp Bearer allowlist. Carries the `type`
+// discriminator and the API-key `apiKeyId`, on top of the access-token fields.
+export interface McpBearerPayload {
+  type?: JwtType;
   sub?: string;
   email?: string;
   workspaceId?: string;
   sessionId?: string;
-}> {
-  return (token: string) => tokenService.verifyJwt(token, JwtType.ACCESS);
+  apiKeyId?: string;
+}
+
+// Minimal structural shape of the TokenService.verifyJwtOneOf method.
+export interface OneOfJwtVerifier {
+  verifyJwtOneOf: (
+    token: string,
+    allowed: JwtType[],
+  ) => Promise<McpBearerPayload>;
+}
+
+/**
+ * Bind a TokenService-like verifier into a one-arg `verifyJwtOneOf(token)` that
+ * pins the /mcp Bearer ALLOWLIST to exactly {ACCESS, API_KEY}. This is the single
+ * place the /mcp Bearer path pins the token type: the /mcp Bearer slot
+ * legitimately accepts either an ACCESS token (a
+ * human's session token) OR an API_KEY token (an agent's key), but NOTHING else
+ * (collab/exchange/attachment/etc. are rejected with the generic type error).
+ * The allowlist is fixed here rather than at the call site, and the signature is
+ * verified exactly once (see verifyMcpBearer).
+ */
+export function bindMcpBearerVerifier(
+  tokenService: OneOfJwtVerifier,
+): (token: string) => Promise<McpBearerPayload> {
+  return (token: string) =>
+    tokenService.verifyJwtOneOf(token, [JwtType.ACCESS, JwtType.API_KEY]);
+}
+
+// Deps for the /mcp Bearer router. `verifyJwtOneOf` is the one-arg verifier bound
+// above (allowlist {ACCESS, API_KEY}); the ACCESS-specific revocation/disabled
+// deps mirror BearerVerifyDeps; `validateApiKey` is the SHARED api-key row-check.
+export interface McpBearerDeps
+  extends Omit<BearerVerifyDeps, 'verifyJwt'> {
+  verifyJwtOneOf: (token: string) => Promise<McpBearerPayload>;
+  // Row-check for an API_KEY principal — the SAME validator REST uses. Throws
+  // UnauthorizedException on a definite deny; PROPAGATES an infra error (→ 5xx),
+  // never masking it as a 401. Not a login attempt: the Basic limiter is not
+  // involved on this path.
+  validateApiKey: (payload: McpBearerPayload) => Promise<unknown>;
+}
+
+/**
+ * Verify a /mcp Bearer token that may be an ACCESS token OR an API_KEY token, and
+ * route by type. The signature is verified EXACTLY ONCE (verifyJwtOneOf); the
+ * result is reused so the ACCESS branch does not re-verify.
+ *
+ *   - API_KEY -> bind to THIS instance's workspace FIRST (a token for another
+ *     workspace is rejected), THEN run the shared `validateApiKey` row-check.
+ *     No session/limiter involvement (an API key is not a login).
+ *   - ACCESS  -> the unchanged `verifyBearerAccess` (session-active + not-disabled
+ *     checks), fed a closure over the already-verified payload so "verify once"
+ *     and "helper unchanged" coexist.
+ *
+ * Throws UnauthorizedException on any auth failure (uniform generic message — no
+ * enumeration of why); propagates an infra error from `validateApiKey` as itself.
+ */
+export async function verifyMcpBearer(
+  token: string,
+  deps: McpBearerDeps,
+): Promise<{ sub?: string; email?: string }> {
+  const generic = 'Invalid or expired token';
+  const payload = await deps.verifyJwtOneOf(token);
+
+  if (payload.type === JwtType.API_KEY) {
+    if (!payload.sub || !payload.workspaceId) {
+      throw new UnauthorizedException(generic);
+    }
+    // Instance-binding (mirrors verifyBearerAccess): reject an API_KEY token
+    // minted for a different workspace before touching the DB.
+    if (
+      deps.expectedWorkspaceId &&
+      payload.workspaceId !== deps.expectedWorkspaceId
+    ) {
+      throw new UnauthorizedException(generic);
+    }
+    // Shared row-check. A definite deny throws Unauthorized; an infra error
+    // propagates (→ 5xx), which the caller must NOT convert to a 401.
+    await deps.validateApiKey(payload);
+    return { sub: payload.sub };
+  }
+
+  // ACCESS: reuse verifyBearerAccess WITHOUT re-verifying the signature.
+  return verifyBearerAccess(token, {
+    verifyJwt: async () => payload,
+    expectedWorkspaceId: deps.expectedWorkspaceId,
+    findUser: deps.findUser,
+    findActiveSession: deps.findActiveSession,
+  });
 }
 
 // Minimal shapes for the Bearer revocation/disabled check. Kept structural so
@@ -728,18 +793,24 @@ export async function resolveMcpSessionConfig(
     };
   }
 
-  // --- 2) fallback A: Bearer access-JWT (user-supplied token) ---
+  // --- 2) fallback A: Bearer JWT (user-supplied ACCESS or agent API_KEY) ---
   const bearer = extractBearer(authHeader);
   if (bearer) {
     let payload: { sub?: string; email?: string };
     try {
       payload = await deps.verifyAccessJwt(bearer);
     } catch (err) {
-      const message =
-        err instanceof Error && err.message
-          ? err.message
-          : 'Invalid or expired token';
-      throw new UnauthorizedException(message);
+      // Anti-enumeration (Bearer leg): EVERY auth failure surfaces the SAME
+      // generic 401 — expired/revoked/wrong-type/unknown are indistinguishable
+      // to the caller (its reaction is identical either way). But an UNEXPECTED
+      // (infra) error is NOT an auth verdict: rethrow it AS ITSELF so the surface
+      // maps it to 5xx (mapAuthResultToResponse), never masking a DB/Redis
+      // outage as a bad token. verifyMcpBearer throws UnauthorizedException on a
+      // definite deny and lets an infra error from validateApiKey propagate.
+      if (err instanceof UnauthorizedException) {
+        throw new UnauthorizedException('Invalid or expired token');
+      }
+      throw err;
     }
     return {
       config: { apiUrl, getToken: async () => bearer },

apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts

@@ -115,6 +115,7 @@ function makeService(opts: {
     undefined as never, // userRepo
     undefined as never, // userSessionRepo
     moduleRef as never, // moduleRef (read by the MFA branch)
+    undefined as never, // apiKeyService (unused by the login-gate path)
     undefined as never, // sandboxStore (unused by the login-gate path)
   );
   // Stop the constructor's unref'd sweep timer leaking across tests.

apps/server/src/integrations/mcp/mcp.module.ts

@@ -4,13 +4,16 @@ import { McpService } from './mcp.service';
 import { DatabaseModule } from '@docmost/db/database.module';
 import { AuthModule } from '../../core/auth/auth.module';
 import { TokenModule } from '../../core/auth/token.module';
+import { ApiKeyModule } from '../../core/api-key/api-key.module';
 
 // Community MCP feature: the server itself serves the Model Context Protocol
 // over HTTP at /mcp. DatabaseModule (global) provides WorkspaceRepo. AuthModule
 // supplies AuthService (per-user HTTP-Basic login validation) and TokenModule
-// supplies TokenService (Bearer access-JWT verification for the token fallback).
+// supplies TokenService (Bearer JWT verification for the token path). ApiKeyModule
+// supplies ApiKeyService (the shared api-key row-check for the API_KEY Bearer
+// branch, so an agent authenticates with a key instead of the bcrypt Basic path).
 @Module({
-  imports: [DatabaseModule, AuthModule, TokenModule],
+  imports: [DatabaseModule, AuthModule, TokenModule, ApiKeyModule],
   controllers: [McpController],
   providers: [McpService],
 })

apps/server/src/integrations/mcp/mcp.service.spec.ts

@@ -6,9 +6,10 @@ import {
   isCredentialsFailure,
   isInitializeRequestBody,
   verifyBearerAccess,
+  verifyMcpBearer,
+  bindMcpBearerVerifier,
   sharedTokenMatches,
   clientIp,
-  bindAccessJwtVerifier,
   extractBearer,
   decideBasicGate,
   mapAuthResultToResponse,
@@ -524,13 +525,28 @@ describe('resolveMcpSessionConfig', () => {
     expect(resolved.identity).toBe('bearer:user-9');
   });
 
-  it('Bearer invalid -> specific 401 from verifyAccessJwt', async () => {
+  it('Bearer invalid -> UNIFORM generic 401 (anti-enumeration, reason not leaked)', async () => {
+    // #501: the Bearer leg no longer surfaces the specific reason. Whether the
+    // token is expired, revoked, wrong-type or unknown, the caller sees ONE bare
+    // 'Invalid or expired token' — an agent's reaction is identical, and a leaked
+    // class would be an enumeration oracle.
     const verifyAccessJwt = jest
       .fn()
       .mockRejectedValue(new UnauthorizedException('jwt expired'));
     await expect(
       resolveMcpSessionConfig('Bearer expired', makeDeps({ verifyAccessJwt })),
-    ).rejects.toThrow('jwt expired');
+    ).rejects.toThrow('Invalid or expired token');
+  });
+
+  it('Bearer INFRA error -> propagates (NOT masked as 401)', async () => {
+    // A non-UnauthorizedException (e.g. a DB outage in the api-key row-check) is
+    // not an auth verdict: it must propagate so the surface maps it to 5xx.
+    const verifyAccessJwt = jest
+      .fn()
+      .mockRejectedValue(new Error('connection terminated'));
+    await expect(
+      resolveMcpSessionConfig('Bearer x', makeDeps({ verifyAccessJwt })),
+    ).rejects.toThrow('connection terminated');
   });
 
   it('no creds + env service account configured -> service-account config', async () => {
@@ -1001,48 +1017,104 @@ describe('clientIp (XFF-fallback precedence, item 5)', () => {
   });
 });
 
-describe('bindAccessJwtVerifier enforces JwtType.ACCESS (item 3)', () => {
-  it('calls TokenService.verifyJwt with JwtType.ACCESS as the second argument', async () => {
-    // Mock TokenService: assert the type literal is pinned to ACCESS so swapping
-    // to REFRESH (or omitting the type) breaks this test.
-    const verifyJwt = jest
+describe('bindMcpBearerVerifier pins the {ACCESS, API_KEY} allowlist (#501)', () => {
+  it('calls verifyJwtOneOf with exactly [ACCESS, API_KEY]', async () => {
+    const verifyJwtOneOf = jest
       .fn()
-      .mockResolvedValue({ sub: 'user-1', workspaceId: 'ws-1' });
-    const verify = bindAccessJwtVerifier({ verifyJwt });
+      .mockResolvedValue({ type: JwtType.API_KEY, sub: 'u-1' });
+    await bindMcpBearerVerifier({ verifyJwtOneOf })('the.jwt');
+    expect(verifyJwtOneOf).toHaveBeenCalledWith('the.jwt', [
+      JwtType.ACCESS,
+      JwtType.API_KEY,
+    ]);
+    // Pin the concrete enum values too.
+    expect(verifyJwtOneOf.mock.calls[0][1]).toEqual(['access', 'api_key']);
+  });
+});
 
-    await verify('the.access.jwt');
-
-    expect(verifyJwt).toHaveBeenCalledTimes(1);
-    expect(verifyJwt).toHaveBeenCalledWith('the.access.jwt', JwtType.ACCESS);
-    // Pin the real enum value too, so renaming/repointing the enum member is caught.
-    expect(verifyJwt.mock.calls[0][1]).toBe('access');
+describe('verifyMcpBearer routes by token type (#501)', () => {
+  const accessDeps = (over: any = {}) => ({
+    verifyJwtOneOf: jest.fn(),
+    expectedWorkspaceId: 'ws-1',
+    findUser: jest.fn().mockResolvedValue({ deactivatedAt: null }),
+    findActiveSession: jest
+      .fn()
+      .mockResolvedValue({ userId: 'u-1', workspaceId: 'ws-1' }),
+    validateApiKey: jest.fn(),
+    ...over,
   });
 
-  it('passes through the verified payload', async () => {
-    const payload = { sub: 'user-9', email: 'u@e.com', workspaceId: 'ws-1' };
-    const verifyJwt = jest.fn().mockResolvedValue(payload);
-    await expect(
-      bindAccessJwtVerifier({ verifyJwt })('t'),
-    ).resolves.toBe(payload);
+  it('API_KEY -> row-checks via validateApiKey and does NOT touch session/limiter', async () => {
+    const deps = accessDeps({
+      verifyJwtOneOf: jest.fn().mockResolvedValue({
+        type: JwtType.API_KEY,
+        sub: 'svc-1',
+        workspaceId: 'ws-1',
+        apiKeyId: 'k-1',
+      }),
+      validateApiKey: jest.fn().mockResolvedValue({ user: { id: 'svc-1' } }),
+    });
+    const res = await verifyMcpBearer('tok', deps);
+    expect(deps.validateApiKey).toHaveBeenCalledTimes(1);
+    // No session lookup on the api-key path (not a login).
+    expect(deps.findActiveSession).not.toHaveBeenCalled();
+    expect(res).toEqual({ sub: 'svc-1' });
   });
 
-  // The Bearer revocation/disabled checks (verifyBearerAccess) are covered above;
-  // this binds the ACCESS-type enforcement that verifyMcpBearer wires in.
-  it('feeds verifyBearerAccess so the whole Bearer chain enforces ACCESS', async () => {
-    const verifyJwt = jest.fn().mockResolvedValue({
-      sub: 'user-1',
+  it('API_KEY for ANOTHER workspace -> rejected before the row-check', async () => {
+    const deps = accessDeps({
+      verifyJwtOneOf: jest.fn().mockResolvedValue({
+        type: JwtType.API_KEY,
+        sub: 'svc-1',
+        workspaceId: 'ws-OTHER',
+        apiKeyId: 'k-1',
+      }),
+      validateApiKey: jest.fn(),
+    });
+    await expect(verifyMcpBearer('tok', deps)).rejects.toBeInstanceOf(
+      UnauthorizedException,
+    );
+    expect(deps.validateApiKey).not.toHaveBeenCalled();
+  });
+
+  it('API_KEY infra error from validateApiKey PROPAGATES (not masked)', async () => {
+    const boom = new Error('db down');
+    const deps = accessDeps({
+      verifyJwtOneOf: jest.fn().mockResolvedValue({
+        type: JwtType.API_KEY,
+        sub: 'svc-1',
+        workspaceId: 'ws-1',
+        apiKeyId: 'k-1',
+      }),
+      validateApiKey: jest.fn().mockRejectedValue(boom),
+    });
+    await expect(verifyMcpBearer('tok', deps)).rejects.toBe(boom);
+  });
+
+  it('ACCESS -> runs the session/disabled checks and does NOT call validateApiKey', async () => {
+    const deps = accessDeps({
+      verifyJwtOneOf: jest.fn().mockResolvedValue({
+        type: JwtType.ACCESS,
+        sub: 'u-1',
+        workspaceId: 'ws-1',
+        sessionId: 'sess-1',
+        email: 'u@e.com',
+      }),
+    });
+    const res = await verifyMcpBearer('tok', deps);
+    expect(deps.findActiveSession).toHaveBeenCalledWith('sess-1');
+    expect(deps.validateApiKey).not.toHaveBeenCalled();
+    expect(res).toEqual({ sub: 'u-1', email: 'u@e.com' });
+  });
+
+  it('verifies the signature exactly ONCE (single verifyJwtOneOf, no re-verify)', async () => {
+    const verifyJwtOneOf = jest.fn().mockResolvedValue({
+      type: JwtType.ACCESS,
+      sub: 'u-1',
       workspaceId: 'ws-1',
-      sessionId: 'sess-1',
     });
-    const res = await verifyBearerAccess('t', {
-      verifyJwt: bindAccessJwtVerifier({ verifyJwt }),
-      findUser: jest.fn().mockResolvedValue({ deactivatedAt: null }),
-      findActiveSession: jest
-        .fn()
-        .mockResolvedValue({ userId: 'user-1', workspaceId: 'ws-1' }),
-    });
-    expect(verifyJwt).toHaveBeenCalledWith('t', JwtType.ACCESS);
-    expect(res).toEqual({ sub: 'user-1', email: undefined });
+    await verifyMcpBearer('tok', accessDeps({ verifyJwtOneOf }));
+    expect(verifyJwtOneOf).toHaveBeenCalledTimes(1);
   });
 });
 
@@ -1198,6 +1270,7 @@ describe('McpService.onModuleDestroy — CollabSession teardown (#486)', () => {
       {} as any,
       {} as any,
       {} as any,
+      {} as any,
     );
   }
 

apps/server/src/integrations/mcp/mcp.service.ts

@@ -14,16 +14,17 @@ import { UserSessionRepo } from '@docmost/db/repos/session/user-session.repo';
 import { AuthService } from '../../core/auth/services/auth.service';
 import { TokenService } from '../../core/auth/services/token.service';
 import { validateSsoEnforcement } from '../../core/auth/auth.util';
-import { JwtPayload } from '../../core/auth/dto/jwt-payload';
+import { JwtApiKeyPayload } from '../../core/auth/dto/jwt-payload';
 import { Workspace } from '@docmost/db/types/entity.types';
+import { ApiKeyService } from '../../core/api-key/api-key.service';
 import {
   FailedLoginLimiter,
   resolveMcpSessionConfig,
-  verifyBearerAccess,
+  verifyMcpBearer,
   isInitializeRequestBody,
   sharedTokenMatches,
   clientIp,
-  bindAccessJwtVerifier,
+  bindMcpBearerVerifier,
   decideBasicGate,
   mapAuthResultToResponse,
   DocmostMcpConfig,
@@ -105,6 +106,10 @@ export class McpService implements OnModuleDestroy {
     private readonly userRepo: UserRepo,
     private readonly userSessionRepo: UserSessionRepo,
     private readonly moduleRef: ModuleRef,
+    // Shared api-key row-check for the /mcp API_KEY Bearer branch (same validator
+    // REST uses). Also lets an agent authenticate to /mcp with an api key instead
+    // of the bcrypt Basic path, so parallel reads stop starving the limiter.
+    private readonly apiKeyService: ApiKeyService,
     // Shared singleton in-RAM blob store backing the stash tool.
     private readonly sandboxStore: SandboxStore,
   ) {
@@ -194,37 +199,41 @@ export class McpService implements OnModuleDestroy {
     }
   }
 
-  // Bearer access-JWT verification for the /mcp token fallback. verifyJwt only
-  // checks signature/exp/type, but a logged-out (revoked) or disabled user can
-  // still hold an unexpired access JWT. JwtStrategy additionally checks the
-  // session is active and the user is not disabled; we mirror those exact checks
-  // here so the MCP Bearer path is not weaker than the normal cookie/header path.
+  // Bearer verification for the /mcp token path. The Bearer slot accepts EITHER
+  // an ACCESS token (a human session token) OR an API_KEY token (an agent's key)
+  // — the allowlist is pinned in bindMcpBearerVerifier. An ACCESS token is
+  // checked exactly as JwtStrategy does (signature/exp/type + session-active +
+  // not-disabled), so the MCP path is not weaker than the cookie/header path. An
+  // API_KEY token is HMAC-verified (microseconds) then row-checked via the shared
+  // ApiKeyService.validate — NOT a login attempt, so the Basic bcrypt path and
+  // its anti-brute-force limiter are never touched (the parallel-reads fix).
   private async verifyMcpBearer(
     token: string,
   ): Promise<{ sub?: string; email?: string }> {
-    // Resolve THIS instance's workspace so verifyBearerAccess can bind the
-    // token's `workspaceId` claim to it (mirrors JwtStrategy). The community
-    // build is single-workspace (findFirst), so this is the default workspace
-    // and the check is a no-op here; it only rejects a foreign-workspace token
-    // in a multi-workspace deployment. Undefined (no workspace configured) means
-    // no check — the credentials path would already have failed with no
-    // workspace, and an undefined here keeps the helper a no-op rather than
-    // rejecting every token.
+    // Resolve THIS instance's workspace so the router can bind the token's
+    // `workspaceId` claim to it (mirrors JwtStrategy). The community build is
+    // single-workspace (findFirst), so this is the default workspace and the
+    // check is a no-op here; it only rejects a foreign-workspace token in a
+    // multi-workspace deployment. Undefined (no workspace configured) means no
+    // check — the credentials path would already have failed with no workspace.
     const instanceWorkspace = await this.workspaceRepo.findFirst();
-    // The revocation/disabled decision logic lives in the framework-free
-    // verifyBearerAccess helper (unit-testable without the heavy auth graph);
-    // this method only wires in the concrete TokenService + repos.
-    return verifyBearerAccess(token, {
-      // The JwtType.ACCESS enforcement lives in bindAccessJwtVerifier (a pure,
-      // testable seam) so the type literal cannot silently drift to REFRESH.
-      verifyJwt: bindAccessJwtVerifier(this.tokenService) as (
-        t: string,
-      ) => Promise<JwtPayload>,
+    // The type-routing + revocation/disabled decision logic lives in the
+    // framework-free verifyMcpBearer helper (unit-testable without the heavy auth
+    // graph); this method only wires in the concrete TokenService + repos + the
+    // shared api-key validator.
+    return verifyMcpBearer(token, {
+      // The {ACCESS, API_KEY} allowlist enforcement lives in bindMcpBearerVerifier
+      // (a pure, testable seam) so the type set cannot silently drift.
+      verifyJwtOneOf: bindMcpBearerVerifier(this.tokenService),
       expectedWorkspaceId: instanceWorkspace?.id,
       findUser: (sub, workspaceId) =>
         this.userRepo.findById(sub, workspaceId),
       findActiveSession: (sessionId) =>
         this.userSessionRepo.findActiveById(sessionId),
+      // Shared with REST: a definite deny throws Unauthorized, an infra error
+      // propagates (→ 5xx). The /mcp bearer catch must preserve that distinction.
+      validateApiKey: (payload) =>
+        this.apiKeyService.validate(payload as JwtApiKeyPayload),
     });
   }
 

apps/server/test/integration/ai-chat-stream.int-spec.ts

@@ -322,20 +322,21 @@ describe('AiChatService.stream [integration]', () => {
   });
 
   /**
-   * #332 deferred tool loading, the ON path. The riskiest property is that the
-   * per-turn `activatedTools` Set is created FRESH inside each stream() call, so a
-   * tool a previous turn activated via loadTools is NOT still active when the next
-   * turn starts — the new turn begins "cold" (CORE + loadTools only). The unit
-   * tests only exercise pure prepareAgentStep with hand-fed Sets; this pins the
-   * real wiring end-to-end (loadTools.execute -> activatedTools -> prepareStep ->
-   * per-step activeTools) against the real streamText loop, and proves there is no
-   * cross-turn leak. We drive a MockLanguageModelV3 whose step 1 calls
-   * loadTools(['createPage']) and assert, via the model's recorded per-step
-   * CallOptions.tools (the AI SDK filters the provider tool list by activeTools),
-   * that the deferred tool becomes active on the SAME turn's next step but NOT on a
-   * fresh turn's first step.
+   * #332 + #490 deferred tool loading, the ON path. Turn 1 starts COLD (CORE +
+   * loadTools only) and activates a deferred tool via loadTools; that activation
+   * is PERSISTED into the chat's metadata.activatedTools (#490) so the NEXT turn
+   * SEEDS from it and the tool is active from the fresh turn's FIRST step — the
+   * model never re-runs loadTools to re-activate the same tool. The unit tests
+   * only exercise pure prepareAgentStep with hand-fed Sets; this pins the real
+   * wiring end-to-end (loadTools.execute -> activatedTools -> persist -> next-turn
+   * seed -> prepareStep -> per-step activeTools) against the real streamText loop.
+   * We drive a MockLanguageModelV3 whose step 1 calls loadTools(['createPage'])
+   * and assert, via the model's recorded per-step CallOptions.tools (the AI SDK
+   * filters the provider tool list by activeTools), that the deferred tool becomes
+   * active on the SAME turn's next step AND, seeded from metadata, on the next
+   * turn's first step.
    */
-  describe('deferred tool loading ON — per-turn activation, no leak (#332)', () => {
+  describe('deferred tool loading ON — cross-turn activation persistence (#332 + #490)', () => {
     // A stub deferred (non-core) tool the agent can activate. Its execute is never
     // called — the model only needs to SEE it become active — but it must be a
     // valid AI-SDK tool so the SDK includes it in a step's tool list once active.
@@ -451,7 +452,7 @@ describe('AiChatService.stream [integration]', () => {
       } as any);
     }
 
-    it('activates a deferred tool for the SAME turn, and a NEW turn starts cold (no leak)', async () => {
+    it('activates a deferred tool for the SAME turn, and a NEW turn SEEDS it from persisted chat metadata (#490)', async () => {
       const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
 
       // --- Turn 1: loadTools(createPage) on step 1, then answer on step 2. ---
@@ -474,7 +475,7 @@ describe('AiChatService.stream [integration]', () => {
       // Step 2 of the SAME turn sees the just-activated deferred tool.
       expect(step2Tools).toContain('createPage');
 
-      // --- Turn 2 on the SAME chat: must start cold again. ---
+      // --- Turn 2 on the SAME chat: seeds the persisted activation (#490). ---
       const model2 = new MockLanguageModelV3({
         doStream: async () => ({ stream: successStream() }),
       } as any);
@@ -485,9 +486,10 @@ describe('AiChatService.stream [integration]', () => {
 
       const nextTurnFirstStep = toolNames(model2.doStreamCalls[0]);
       expect(nextTurnFirstStep).toContain('loadTools');
-      // The activated set is per-turn: the prior turn's createPage did NOT leak,
-      // so the fresh turn's first step sees it deferred again.
-      expect(nextTurnFirstStep).not.toContain('createPage');
+      // #490: activation PERSISTS across turns — turn 1 wrote createPage into the
+      // chat's metadata.activatedTools, so the next turn seeds from it and the
+      // deferred tool is active from the FIRST step (no need to re-run loadTools).
+      expect(nextTurnFirstStep).toContain('createPage');
     });
   });
 });

apps/server/test/integration/page-work-time.int-spec.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { Kysely } from 'kysely';
+import { PageHistoryRepo } from '../../src/database/repos/page/page-history.repo';
+import { PageHistoryService } from '../../src/core/page/services/page-history.service';
+import { computeWorkTime } from '../../src/core/page/work-time';
+import {
+  getTestDb,
+  destroyTestDb,
+  createWorkspace,
+  createSpace,
+  createPage,
+  createUser,
+  createChat,
+} from './db';
+
+/**
+ * #395 — real-Postgres coverage for the work-time timeline projection and the
+ * service that computes the estimate. The pure sessionizer is unit-tested
+ * exhaustively (compute-work-time.spec.ts); this asserts the SQL projection
+ * (right rows, ASC, no `content`) and that the service's numbers agree with the
+ * pure core over the exact rows the DB returns.
+ */
+describe('PageHistory work-time [integration]', () => {
+  let db: Kysely<any>;
+  let repo: PageHistoryRepo;
+  let service: PageHistoryService;
+  let workspaceId: string;
+  let spaceId: string;
+  let pageId: string;
+  let userId: string;
+  let chatId: string;
+
+  const MIN = 60 * 1000;
+
+  beforeAll(async () => {
+    db = getTestDb();
+    repo = new PageHistoryRepo(db as any);
+    service = new PageHistoryService(repo);
+    workspaceId = (await createWorkspace(db)).id;
+    spaceId = (await createSpace(db, workspaceId)).id;
+    pageId = (await createPage(db, { workspaceId, spaceId })).id;
+    userId = (await createUser(db, workspaceId)).id;
+    chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
+  });
+
+  afterAll(async () => {
+    await destroyTestDb();
+  });
+
+  async function insertHistory(rows: Array<{
+    createdAt: string;
+    source: string | null;
+    chat?: string | null;
+    kind?: string | null;
+    content?: unknown;
+  }>) {
+    for (const r of rows) {
+      await db
+        .insertInto('pageHistory')
+        .values({
+          id: randomUUID(),
+          pageId,
+          spaceId,
+          workspaceId,
+          title: 'x',
+          content: r.content ?? { type: 'doc', content: [] },
+          lastUpdatedById: userId,
+          lastUpdatedSource: r.source,
+          lastUpdatedAiChatId: r.chat ?? null,
+          kind: r.kind ?? null,
+          createdAt: new Date(r.createdAt),
+        })
+        .execute();
+    }
+  }
+
+  it('findTimelineByPageId projects the cheap columns, ASC, without content', async () => {
+    await insertHistory([
+      { createdAt: '2026-07-04T19:54:00Z', source: 'user', kind: 'manual' },
+      { createdAt: '2026-07-04T03:40:00Z', source: 'user', kind: null },
+      { createdAt: '2026-07-04T15:43:00Z', source: 'agent', chat: chatId, kind: 'agent' },
+    ]);
+
+    const timeline = await repo.findTimelineByPageId(pageId);
+    expect(timeline).toHaveLength(3);
+    // Sorted oldest → newest.
+    const times = timeline.map((r) => new Date(r.createdAt).getTime());
+    expect(times).toEqual([...times].sort((a, b) => a - b));
+    // Projection carries exactly the sessionizer's inputs, and NO content.
+    for (const row of timeline) {
+      expect(row).toHaveProperty('createdAt');
+      expect(row).toHaveProperty('lastUpdatedById');
+      expect(row).toHaveProperty('lastUpdatedSource');
+      expect(row).toHaveProperty('lastUpdatedAiChatId');
+      expect(row).toHaveProperty('kind');
+      expect(row).not.toHaveProperty('content');
+    }
+    // Agent row keeps its provenance.
+    const agent = timeline.find((r) => r.lastUpdatedSource === 'agent');
+    expect(agent?.lastUpdatedAiChatId).toBe(chatId);
+  });
+
+  it('service estimate matches the pure core and satisfies Σ perDay == workMs', async () => {
+    const rows = await repo.findTimelineByPageId(pageId);
+    const pure = computeWorkTime(rows);
+
+    const result = await service.computeWorkTime(pageId, 'UTC');
+    expect(result.workMs).toBe(pure.workMs);
+    expect(result.agentOnlyMs).toBe(pure.agentOnlyMs);
+    expect(result.tz).toBe('UTC');
+    expect(result.config.tGap).toBe(15 * MIN);
+
+    const sumActive = result.perDay.reduce((a, d) => a + d.activeMs, 0);
+    expect(sumActive).toBe(result.workMs);
+
+    // The 3 seeded rows sessionize into ≤ their span; not the naive span.
+    const naive =
+      new Date('2026-07-04T19:54:00Z').getTime() -
+      new Date('2026-07-04T03:40:00Z').getTime();
+    expect(result.workMs).toBeGreaterThan(0);
+    expect(result.workMs).toBeLessThan(naive);
+  });
+
+  it('an unknown timezone surfaces as a RangeError (controller maps to 400)', async () => {
+    await expect(
+      service.computeWorkTime(pageId, 'Not/AZone'),
+    ).rejects.toBeInstanceOf(RangeError);
+  });
+
+  it('a page with no history → zeros, no days', async () => {
+    const emptyPage = (await createPage(db, { workspaceId, spaceId })).id;
+    const result = await service.computeWorkTime(emptyPage, 'UTC');
+    expect(result.workMs).toBe(0);
+    expect(result.agentOnlyMs).toBe(0);
+    expect(result.perDay).toEqual([]);
+  });
+});

packages/mcp/src/lib/drawio-xml.ts

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

packages/mcp/test/unit/drawio-xml.test.mjs

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