Merge remote-tracking branch 'gitea/develop' into fix/534-mcp-spaceid

The list-only cap assumed a well-formed prefix; a pathologically long
agent-supplied spaceId (unvalidated for length) lives in the prefix and bypassed
the cap. Add the same unconditional final slice formatDocmostAxiosError uses, so
the WHOLE message is bounded regardless of spaceId length. No-op for normal
inputs (36-char UUID) where the list cap already keeps it <= 300.

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

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

@@ -1427,20 +1427,5 @@
   "Boundary": "Boundary",
   "Autosave": "Autosave",
   "Only versions": "Only versions",
-  "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"
+  "No saved versions yet.": "No saved versions yet."
 }

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

@@ -1442,20 +1442,5 @@
   "Boundary": "Граница",
   "Autosave": "Автосейв",
   "Only versions": "Только версии",
-  "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}} м"
+  "No saved versions yet.": "Пока нет сохранённых версий."
 }

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

@@ -1,45 +0,0 @@
-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

@@ -1,45 +0,0 @@
-// #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

@@ -1,25 +0,0 @@
-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

@@ -1,171 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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

@@ -1,82 +0,0 @@
-/* #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

@@ -1,37 +0,0 @@
-// #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,7 +51,6 @@ 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,
@@ -266,8 +265,6 @@ function PageActionMenu({ readOnly, onSaveVersion }: PageActionMenuProps) {
 
   return (
     <>
-      {page?.id && <WorkTimeStat pageId={page.id} />}
-
       <Menu
         shadow="xl"
         position="bottom-end"

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

@@ -5,7 +5,6 @@ import {
   IsOptional,
   IsString,
   IsUUID,
-  MaxLength,
 } from 'class-validator';
 import { Transform } from 'class-transformer';
 
@@ -48,17 +47,6 @@ 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,8 +1,3 @@
-import {
-  BadRequestException,
-  ForbiddenException,
-  NotFoundException,
-} from '@nestjs/common';
 import { PageController } from './page.controller';
 
 // Direct instantiation with stub deps. The Test.createTestingModule form failed
@@ -27,88 +22,4 @@ 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,7 +21,6 @@ import {
   PageHistoryIdDto,
   PageIdDto,
   PageInfoDto,
-  PageWorkTimeDto,
 } from './dto/page.dto';
 import { PageHistoryService } from './services/page-history.service';
 import { AuthUser } from '../../common/decorators/auth-user.decorator';
@@ -525,32 +524,6 @@ 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,23 +3,6 @@ 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 {
@@ -40,33 +23,4 @@ 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

@@ -1,129 +0,0 @@
-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

@@ -1,180 +0,0 @@
-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

@@ -1,358 +0,0 @@
-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

@@ -1,274 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,102 +0,0 @@
-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

@@ -1,73 +0,0 @@
-/**
- * #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/repos/page/page-history.repo.ts

@@ -157,44 +157,6 @@ 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/test/integration/page-work-time.int-spec.ts

@@ -1,137 +0,0 @@
-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/client.ts

@@ -31,7 +31,11 @@ import { TransformsMixin, type ITransformsMixin } from "./client/transforms.js";
 // existing importer (index.ts, http.ts, stdio.ts, the in-app host) keeps working
 // with ZERO changes.
 export type { DocmostMcpConfig, SandboxPut } from "./client/context.js";
-export { formatDocmostAxiosError, assertFullUuid } from "./client/errors.js";
+export {
+  formatDocmostAxiosError,
+  assertFullUuid,
+  formatSpaceNotAccessible,
+} from "./client/errors.js";
 
 // Branded canonical page-identity type (#435): the internal page UUID is a
 // distinct nominal type so an unresolved raw/slug string can't be swapped into

packages/mcp/src/client/comments.ts

@@ -725,10 +725,15 @@ export function CommentsMixin<TBase extends GConstructor<DocmostClientContext>>(
     // The subtree scope (parentPageId given) already INCLUDES the root node
     // itself: /pages/tree seeds getPageAndDescendants with id = parentPageId, so
     // no separate getPageRaw fetch for the parent is needed.
-    const { pages: pagesInScope, truncated } = await this.enumerateSpacePages(
-      spaceId,
-      parentPageId,
-    );
+    // #534: the enumerateSpacePages seed (`/pages/tree`) 404s for a bad or
+    // inaccessible spaceId; wrap it so that 404 becomes an actionable "spaceId
+    // not accessible" hint instead of the opaque "Space permissions not found".
+    // Only the whole enumeration is wrapped (the only 404 source here) — see the
+    // wrap-allowlist invariant on withSpaceAccessDiagnostics.
+    const { pages: pagesInScope, truncated } =
+      await this.withSpaceAccessDiagnostics(spaceId, "checkNewComments", () =>
+        this.enumerateSpacePages(spaceId, parentPageId),
+      );
 
     // 2. Fetch comments for each page, keep ones created after since. Runs with
     // bounded concurrency (#490) instead of one-at-a-time — the per-page reads are

packages/mcp/src/client/context.ts

@@ -26,7 +26,10 @@ import {
 import { withPageLock, isUuid } from "../lib/page-lock.js";
 import type { PageId } from "../lib/page-id.js";
 import { getCollabToken, performLogin } from "../lib/auth-utils.js";
-import { formatDocmostAxiosError } from "./errors.js";
+import {
+  formatDocmostAxiosError,
+  formatSpaceNotAccessible,
+} from "./errors.js";
 import { GetPageConversionCache } from "./getpage-cache.js";
 
 // A generic mixin base constructor (issue #450). Each domain mixin is a factory
@@ -117,6 +120,36 @@ function readCollabTokenTtlMs(): number {
   return Number.isFinite(raw) ? Math.max(0, raw) : 5 * 60 * 1000;
 }
 
+/**
+ * Accessible-space index cache TTL in milliseconds (issue #534). Read fresh from
+ * the environment on every access — mirroring readCollabTokenTtlMs above — so a
+ * test or a live rollback can change it without reloading the module.
+ *
+ * The index (see getAccessibleSpaceIndex) is fetched ONLY on the enrich-on-404
+ * slow path to turn an opaque "Space permissions not found" 404 into a factual
+ * "spaceId X is not among your accessible spaces" hint; a short TTL keeps a burst
+ * of failing tool calls from re-sweeping /spaces each time while never widening
+ * the permission-staleness window meaningfully. Default 60s. An EXPLICIT 0 (or
+ * negative) DISABLES the cache (exact fetch-per-enrichment). Unset/unparseable
+ * (NaN) falls back to the 60s default with the cache ON.
+ */
+function readSpacesCacheTtlMs(): number {
+  const raw = parseInt(process.env.MCP_SPACES_CACHE_TTL_MS ?? "", 10);
+  return Number.isFinite(raw) ? Math.max(0, raw) : 60000;
+}
+
+/**
+ * The set of spaces the current token can see, plus a `complete` flag that is
+ * false when the /spaces listing was truncated at the pagination ceiling. Used
+ * by the enrich-on-404 diagnostics: an authoritative membership test is only
+ * possible when `complete` is true (see withSpaceAccessDiagnostics).
+ */
+export type AccessibleSpaceIndex = {
+  ids: Set<string>;
+  spaces: { id: string; name: string }[];
+  complete: boolean;
+};
+
 export abstract class DocmostClientContext {
   protected client: AxiosInstance;
   protected token: string | null = null;
@@ -164,6 +197,27 @@ export abstract class DocmostClientContext {
   // bypassed on a forced refresh (the 401/403 reauth path). null = no token yet.
   protected collabTokenCache: { token: string; mintedAt: number } | null = null;
 
+  // Accessible-space index cache + single-flight (issue #534). TWO separate
+  // fields, mirroring loginPromise (in-flight dedup) vs collabTokenCache
+  // (persistent value):
+  //   - spaceIndexCache: the last SUCCESSFULLY-FETCHED, COMPLETE index plus the
+  //     wall-clock time it was fetched. Written ONLY from a resolved /spaces
+  //     sweep whose result was complete (a truncated list is never cached, since
+  //     it cannot answer "is this spaceId missing?"). Per-instance (a
+  //     DocmostClient is built per user / per chat) so it can never leak across
+  //     identities; invalidated on every identity change exactly like
+  //     collabTokenCache (login() + the 401/403 reauth interceptor).
+  //   - spaceIndexInFlight: dedups concurrent enrich-on-404 fetches into ONE
+  //     /spaces sweep. CRITICAL INVARIANT: this promise is nulled in `.finally`
+  //     on BOTH resolve AND reject — a rejected/settled promise is NEVER
+  //     memoized, so a transient /spaces blip during one failed tool call cannot
+  //     poison the diagnostics for the rest of the session.
+  protected spaceIndexCache: {
+    index: AccessibleSpaceIndex;
+    fetchedAt: number;
+  } | null = null;
+  protected spaceIndexInFlight: Promise<AccessibleSpaceIndex> | null = null;
+
   // Content-addressed conversion cache for getPage (issue #479). Keyed on
   // (canonical pageId, updatedAt, optionsHash) -> the converted Markdown, so a
   // re-read of an UNCHANGED page skips the expensive convertProseMirrorToMarkdown
@@ -281,6 +335,9 @@ export abstract class DocmostClientContext {
           // keep serving a collab token minted under the old one.
           this.token = null;
           this.collabTokenCache = null;
+          // #534: a new identity/login must not keep serving a space index
+          // computed under the old token (same reasoning as collabTokenCache).
+          this.spaceIndexCache = null;
           delete this.client.defaults.headers.common["Authorization"];
           try {
             await this.login();
@@ -413,6 +470,8 @@ export abstract class DocmostClientContext {
           // Identity (re)established: drop any collab token minted under a
           // previous identity so the #435 cache can never outlive it.
           this.collabTokenCache = null;
+          // #534: likewise drop the accessible-space index of the old identity.
+          this.spaceIndexCache = null;
           this.client.defaults.headers.common["Authorization"] =
             `Bearer ${token}`;
         })
@@ -630,13 +689,34 @@ export abstract class DocmostClientContext {
   }
 
   /**
-   * Generic pagination handler for Docmost API endpoints
+   * Generic pagination handler for Docmost API endpoints. Thin wrapper over
+   * paginateAllWithMeta that discards the `truncated` flag — the historical
+   * contract every caller (getSpaces, etc.) relies on. Callers that need to KNOW
+   * whether the result set was complete (e.g. #534's getAccessibleSpaceIndex,
+   * which must not assert "spaceId missing" against a truncated list) call
+   * paginateAllWithMeta directly.
    */
   async paginateAll<T = any>(
     endpoint: string,
     basePayload: Record<string, any> = {},
     limit: number = 100,
   ): Promise<T[]> {
+    return (await this.paginateAllWithMeta<T>(endpoint, basePayload, limit))
+      .items;
+  }
+
+  /**
+   * Generic pagination handler that ALSO surfaces whether the result was
+   * truncated at the MAX_PAGES ceiling. `paginateAll` swallows this flag (it only
+   * warns); callers that must distinguish "complete listing" from "gave up at the
+   * cap" use this overload. `truncated` is true iff the loop stopped at the
+   * ceiling while the server still reported more pages.
+   */
+  async paginateAllWithMeta<T = any>(
+    endpoint: string,
+    basePayload: Record<string, any> = {},
+    limit: number = 100,
+  ): Promise<{ items: T[]; truncated: boolean }> {
     await this.ensureAuthenticated();
 
     const clampedLimit = Math.max(1, Math.min(100, limit));
@@ -697,7 +777,137 @@ export abstract class DocmostClientContext {
       );
     }
 
-    return allItems;
+    return { items: allItems, truncated };
+  }
+
+  /**
+   * The set of spaces the current token can access (issue #534), fetched from the
+   * single source of truth — the `/spaces` listing — with a per-instance
+   * short-TTL cache and single-flight dedup. Used ONLY by the enrich-on-404 slow
+   * path (withSpaceAccessDiagnostics), so the happy path incurs ZERO extra
+   * requests.
+   *
+   * `complete` is `!truncated`: it is false when the /spaces listing was cut at
+   * the pagination ceiling. A truncated index can never authoritatively answer
+   * "is this spaceId missing?", so only a complete result is cached AND only a
+   * complete result is allowed to drive the "not accessible" rewrite.
+   *
+   * Cache/single-flight discipline (see the spaceIndexCache / spaceIndexInFlight
+   * field docs):
+   *   - serve a fresh, complete cached index without any request;
+   *   - otherwise collapse concurrent callers onto ONE in-flight /spaces sweep;
+   *   - write the persistent cache ONLY from a resolved, complete fetch;
+   *   - null the in-flight promise on BOTH resolve and reject (never memoize a
+   *     rejected promise — a transient /spaces failure must be retried fresh).
+   */
+  async getAccessibleSpaceIndex(): Promise<AccessibleSpaceIndex> {
+    const ttl = readSpacesCacheTtlMs();
+
+    // Fast path: a still-fresh, complete cached index needs no request at all.
+    if (
+      ttl > 0 &&
+      this.spaceIndexCache &&
+      Date.now() - this.spaceIndexCache.fetchedAt < ttl
+    ) {
+      return this.spaceIndexCache.index;
+    }
+
+    // Single-flight: a concurrent enrichment joins the in-flight sweep instead of
+    // issuing its own. (A settled/rejected promise is never left here — see the
+    // `.finally` below — so this only ever joins a genuinely in-progress fetch.)
+    if (this.spaceIndexInFlight) return this.spaceIndexInFlight;
+
+    const fetchPromise = (async (): Promise<AccessibleSpaceIndex> => {
+      const { items, truncated } = await this.paginateAllWithMeta("/spaces", {});
+      const spaces = items.map((s: any) => ({
+        id: s?.id,
+        name: s?.name,
+      }));
+      return {
+        ids: new Set(spaces.map((s) => s.id)),
+        spaces,
+        complete: !truncated,
+      };
+    })();
+
+    this.spaceIndexInFlight = fetchPromise
+      .then((index) => {
+        // Cache ONLY a complete result, and only while the cache is enabled.
+        if (ttl > 0 && index.complete) {
+          this.spaceIndexCache = { index, fetchedAt: Date.now() };
+        }
+        return index;
+      })
+      .finally(() => {
+        // CRITICAL (#534): clear the in-flight slot on BOTH resolve and reject.
+        // Nulling on reject too means a transient /spaces error is retried by the
+        // NEXT enrichment with a fresh fetch, never re-serving the rejection.
+        this.spaceIndexInFlight = null;
+      });
+
+    return this.spaceIndexInFlight;
+  }
+
+  /**
+   * Wrap a client method whose 404 means "the supplied spaceId is not accessible"
+   * and, ONLY on that 404, replace the opaque server text ("Space permissions not
+   * found") with a factual, actionable message naming the spaceId and the spaces
+   * the token can actually see (issue #534). A HINT layered on top of the
+   * backend, which stays authoritative — so it FAILS OPEN on ANY uncertainty:
+   * every branch below that is not a confident "this spaceId is genuinely
+   * missing" rethrows the ORIGINAL server error unchanged. The happy path returns
+   * fn()'s value with zero extra requests.
+   *
+   * WRAP-ALLOWLIST INVARIANT (load-bearing — read before wrapping a new method):
+   * among the currently wrapped tools a 404 comes ONLY from the spaceId
+   * membership / space-permissions check — their pageId / rootPageId /
+   * parentPageId branches resolve to 403 or 200, NEVER 404. If a future change
+   * adds a `NotFoundException` to `/pages/tree`, `/pages/recent`,
+   * `/pages/sidebar-pages` or `/search` (e.g. "page not found"), this enrichment
+   * would MISATTRIBUTE that 404 to the spaceId. Re-audit the wrapped call before
+   * relying on this, and only wrap paths where the sole 404 cause is the space.
+   */
+  protected async withSpaceAccessDiagnostics<T>(
+    spaceId: string,
+    mcpName: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    try {
+      return await fn();
+    } catch (e) {
+      // Abort/cap wins FIRST and is detected by the SIGNAL FLAG, not e.name: a
+      // per-call cap may be an AbortSignal.timeout() (reason name "TimeoutError")
+      // or a custom reason, so `e.name === 'AbortError'` is NOT reliable (#534
+      // hole B). A stopped/capped turn must propagate its reason, never trigger a
+      // /spaces sweep or a rewrite.
+      if (this.toolAbortSignal?.aborted) throw e;
+
+      // Only a 404 is enrichable; any other status/shape is a different failure.
+      if (!(axios.isAxiosError(e) && e.response?.status === 404)) throw e;
+
+      let idx: AccessibleSpaceIndex;
+      try {
+        idx = await this.getAccessibleSpaceIndex();
+      } catch (fetchErr) {
+        // The /spaces sweep itself failed. If we were aborted mid-sweep,
+        // propagate the abort reason; otherwise FAIL OPEN with the ORIGINAL
+        // server error rather than a misleading "not found".
+        if (this.toolAbortSignal?.aborted) throw fetchErr;
+        if (process.env.DEBUG) {
+          console.error("space-diag: /spaces fetch failed:", fetchErr);
+        }
+        throw e;
+      }
+
+      // Fail open when the listing is incomplete (can't assert "missing") or when
+      // the spaceId IS present (the 404 is about something else, not the space).
+      if (!idx.complete) throw e;
+      if (idx.ids.has(spaceId)) throw e;
+
+      // Confident: the spaceId is well-formed but not among the accessible
+      // spaces. Replace the opaque server text with the actionable fact.
+      throw new Error(formatSpaceNotAccessible(mcpName, spaceId, idx.spaces));
+    }
   }
 
 

packages/mcp/src/client/errors.ts

@@ -46,6 +46,60 @@ export function assertFullUuid(
   }
 }
 
+// Max number of accessible spaces to enumerate inline in the "space not
+// accessible" message (issue #534) before collapsing the rest into a "(+N ещё)"
+// tail, so a workspace with many spaces cannot blow up the model context.
+const SPACE_LIST_CAP = 10;
+
+/**
+ * Compose the model-facing "spaceId is not accessible" message (issue #534).
+ * This is FACT text about the supplied spaceId that REPLACES the opaque server
+ * string ("Space permissions not found") on the enrich-on-404 path — it names
+ * the exact bad id, lists the spaces the token can actually see (id + name, so
+ * the agent can copy the right id verbatim), and points at `listSpaces`.
+ *
+ * Deliberately Russian: like the other agent-facing tool guidance in this repo,
+ * this is the message the acting agent reads to self-correct.
+ */
+export function formatSpaceNotAccessible(
+  mcpName: string,
+  spaceId: string,
+  spaces: { id: string; name: string }[],
+): string {
+  // No accessible spaces at all — a distinct diagnosis (token has no space
+  // access), not "you picked the wrong one from this list".
+  if (!Array.isArray(spaces) || spaces.length === 0) {
+    return `${mcpName}: spaceId "${spaceId}" недоступен, и доступных тебе спейсов нет — проверь доступ токена / вызови listSpaces.`;
+  }
+
+  const shown = spaces.slice(0, SPACE_LIST_CAP);
+  const remaining = spaces.length - shown.length;
+  const tail =
+    remaining > 0 ? ` (+${remaining} ещё, см. listSpaces)` : "";
+
+  // Cap the whole message at ERROR_MESSAGE_CAP (same budget as
+  // formatDocmostAxiosError) so ~10 long space names cannot blow up the model
+  // context. Truncate ONLY the interpolated space LIST — the fixed prefix (which
+  // carries the bad spaceId) and the fixed suffix (the "…из listSpaces"
+  // instruction) are always kept intact, so the actionable parts survive even
+  // when the list is trimmed.
+  const prefix = `${mcpName}: spaceId "${spaceId}" не найден среди доступных тебе спейсов. Доступные: `;
+  const suffix = ` — скопируй нужный id дословно из listSpaces.`;
+  let listed = shown.map((s) => `${s.id} (${s.name})`).join(", ") + tail;
+  const budget = ERROR_MESSAGE_CAP - prefix.length - suffix.length;
+  if (listed.length > budget) {
+    listed = listed.slice(0, Math.max(0, budget - 1)) + "…";
+  }
+  const message = `${prefix}${listed}${suffix}`;
+  // Unconditional final backstop (mirrors formatDocmostAxiosError): the list
+  // cap above assumes a well-formed prefix, but a pathologically long
+  // agent-supplied spaceId lives in the prefix and would otherwise blow past the
+  // budget. Cap the WHOLE message so nothing bloats the model context.
+  return message.length > ERROR_MESSAGE_CAP
+    ? message.slice(0, ERROR_MESSAGE_CAP - 1) + "…"
+    : message;
+}
+
 // Keep ONLY the pathname of a request (no host, no query string, no fragment)
 // so the message never leaks a host or query params. Resolves a relative
 // config.url against config.baseURL, then discards everything but the path.

packages/mcp/src/client/read.ts

@@ -132,17 +132,29 @@ export function ReadMixin<TBase extends GConstructor<DocmostClientContext>>(Base
       // BFS hit its node cap) had no way to know pages were missing. Return the
       // tree alongside the flag; the primary /pages/tree path is uncapped so this
       // is false there.
-      const { pages, truncated } = await this.enumerateSpacePages(spaceId);
-      return { tree: buildPageTree(pages), truncated };
+      // #534: spaceId is required here; wrap so a bad-spaceId 404 (from the
+      // /pages/tree seed inside enumerateSpacePages) becomes an actionable hint.
+      return this.withSpaceAccessDiagnostics(spaceId, "listPages", async () => {
+        const { pages, truncated } = await this.enumerateSpacePages(spaceId);
+        return { tree: buildPageTree(pages), truncated };
+      });
     }
 
     const clampedLimit = Math.max(1, Math.min(100, limit));
     const payload: Record<string, any> = { limit: clampedLimit, page: 1 };
     if (spaceId) payload.spaceId = spaceId;
-    const response = await this.client.post("/pages/recent", payload);
-    const data = response.data;
-    const items = data.data?.items || data.items || [];
-    return items.map((page: any) => filterPage(page));
+    // #534: only the WITH-spaceId recent path can 404 on space access; wrap it so
+    // that 404 is rewritten. Without a spaceId there is no space to diagnose, so
+    // the wrapper is inert (run the request directly).
+    const runRecent = async () => {
+      const response = await this.client.post("/pages/recent", payload);
+      const data = response.data;
+      const items = data.data?.items || data.items || [];
+      return items.map((page: any) => filterPage(page));
+    };
+    return spaceId
+      ? this.withSpaceAccessDiagnostics(spaceId, "listPages", runRecent)
+      : runRecent();
   }
 
   /**
@@ -174,8 +186,16 @@ export function ReadMixin<TBase extends GConstructor<DocmostClientContext>>(Base
         "getTree: spaceId is required (a page tree is scoped to one space).",
       );
     }
-    const { pages } = await this.enumerateSpacePages(spaceId, rootPageId);
-    return buildPageTree(pages, { shape: "getTree", maxDepth });
+    // #534: the 404 for a bad/inaccessible spaceId surfaces from the
+    // `/pages/tree` seeding step inside enumerateSpacePages (which is NOT in a
+    // try/catch of its own for that case) — wrap the whole body so it is caught
+    // and rewritten into an actionable "spaceId not accessible" message. Only the
+    // space membership check can 404 here (rootPageId 403/200), see the
+    // wrap-allowlist invariant on withSpaceAccessDiagnostics.
+    return this.withSpaceAccessDiagnostics(spaceId, "getTree", async () => {
+      const { pages } = await this.enumerateSpacePages(spaceId, rootPageId);
+      return buildPageTree(pages, { shape: "getTree", maxDepth });
+    });
   }
 
   /**
@@ -700,17 +720,27 @@ export function ReadMixin<TBase extends GConstructor<DocmostClientContext>>(Base
     if (limit !== undefined) {
       payload.limit = Math.max(1, Math.min(50, limit));
     }
-    const response = await this.client.post("/search", payload);
 
-    // Normalize both response shapes: bare array and paginated { items: [...] }
-    const data = response.data?.data;
-    const items = Array.isArray(data) ? data : data?.items || [];
-    const filteredItems = items.map((item: any) => filterSearchResult(item));
+    const runSearch = async () => {
+      const response = await this.client.post("/search", payload);
 
-    return {
-      items: filteredItems,
-      success: response.data?.success || false,
+      // Normalize both response shapes: bare array and paginated { items: [...] }
+      const data = response.data?.data;
+      const items = Array.isArray(data) ? data : data?.items || [];
+      const filteredItems = items.map((item: any) => filterSearchResult(item));
+
+      return {
+        items: filteredItems,
+        success: response.data?.success || false,
+      };
     };
+
+    // #534: a search scoped to a spaceId 404s when that space is inaccessible;
+    // wrap only that case so the 404 becomes an actionable hint. A workspace-wide
+    // search (no spaceId) has no space to diagnose — run it directly (inert).
+    return spaceId
+      ? this.withSpaceAccessDiagnostics(spaceId, "search", runSearch)
+      : runSearch();
   }
 
   }

packages/mcp/test/unit/space-access-diagnostics.test.mjs

@@ -0,0 +1,423 @@
+// Issue #534: enrich-on-404 space-access diagnostics.
+//
+// When a tool is handed a well-formed but non-existent/inaccessible spaceId, the
+// server answers the space-permissions check with an opaque 404 ("Space
+// permissions not found"). The client wrapper (withSpaceAccessDiagnostics) turns
+// ONLY that 404 into an actionable message naming the bad spaceId and the spaces
+// the token can actually see — while FAILING OPEN (rethrowing the original
+// server error unchanged) on every source of uncertainty.
+//
+// These tests drive the assembled DocmostClient with its inner seams
+// (enumerateSpacePages / client.post / paginateAllWithMeta) stubbed at runtime,
+// mirroring the stub-client style of error-diagnostics.test.mjs. Only criterion
+// 9 (createPage is NOT wrapped) uses a real offline http server, because
+// createPage's 404 arrives over a bare-axios multipart path.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import axios, { AxiosError } from "axios";
+import {
+  DocmostClient,
+  formatSpaceNotAccessible,
+} from "../../build/client.js";
+
+// Two accessible spaces (id + name is all getAccessibleSpaceIndex maps/uses).
+const SPACES = [
+  { id: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", name: "Engineering" },
+  { id: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", name: "Design" },
+];
+// A well-formed UUID that is NOT among the accessible spaces.
+const BAD = "99999999-9999-4999-8999-999999999999";
+
+// Build an AxiosError shaped exactly as the response interceptor would hand it
+// on a 404 — status readable, axios.isAxiosError() true.
+function makeAxiosErr(status, url = "/pages/tree", message = "boom") {
+  const config = { method: "post", url, baseURL: "http://host.example/api" };
+  const response = {
+    status,
+    statusText: String(status),
+    data: { message },
+    headers: {},
+    config,
+  };
+  return new AxiosError(
+    `Request failed with status code ${status}`,
+    "ERR_BAD_REQUEST",
+    config,
+    {},
+    response,
+  );
+}
+function make404(url = "/pages/tree") {
+  return makeAxiosErr(404, url, "Space permissions not found");
+}
+
+// A client whose token is pre-set (so ensureAuthenticated never hits the
+// network) and whose /spaces sweep is a counted stub. Individual tests override
+// enumerateSpacePages / client.post to shape the method-under-test's outcome.
+function makeClient({ spaces = SPACES, truncated = false } = {}) {
+  const c = new DocmostClient("http://127.0.0.1:1/api", "u@example.com", "pw");
+  c.token = "t";
+  c.client.defaults.headers.common["Authorization"] = "Bearer t";
+  c._spacesFetches = 0;
+  c.paginateAllWithMeta = async (endpoint) => {
+    if (endpoint === "/spaces") {
+      c._spacesFetches++;
+      return { items: spaces, truncated };
+    }
+    throw new Error(`unexpected paginate endpoint ${endpoint}`);
+  };
+  return c;
+}
+
+// --- Criterion 1: bad spaceId on getTree -> actionable rewrite --------------
+test("getTree with a non-existent spaceId is rewritten into an actionable hint", async () => {
+  const c = makeClient();
+  c.enumerateSpacePages = async () => {
+    throw make404();
+  };
+
+  await assert.rejects(
+    () => c.getTree(BAD),
+    (e) => {
+      assert.ok(e.message.includes(BAD), "names the passed spaceId");
+      // At least one valid "id (name)" pair.
+      assert.ok(
+        e.message.includes(`${SPACES[0].id} (${SPACES[0].name})`),
+        "lists an accessible id (name)",
+      );
+      assert.ok(e.message.includes("listSpaces"), "points at listSpaces");
+      assert.ok(
+        !e.message.includes("Space permissions not found"),
+        "the opaque server text is replaced",
+      );
+      return true;
+    },
+  );
+  assert.equal(c._spacesFetches, 1, "one /spaces sweep on the enrichment path");
+});
+
+// --- Criterion 2: happy path -> no /spaces request --------------------------
+test("getTree with a valid spaceId returns the tree and makes NO /spaces request", async () => {
+  const c = makeClient();
+  // Spy client.post to prove no /spaces POST is issued on the happy path.
+  const posted = [];
+  c.client.post = async (url) => {
+    posted.push(url);
+    throw new Error(`unexpected post ${url}`);
+  };
+  c.enumerateSpacePages = async () => ({ pages: [], truncated: false });
+
+  const res = await c.getTree(SPACES[0].id);
+  assert.ok(Array.isArray(res), "tree returned as before");
+  assert.equal(c._spacesFetches, 0, "no /spaces sweep on the happy path");
+  assert.ok(
+    !posted.includes("/spaces"),
+    "no /spaces POST on the happy path",
+  );
+});
+
+// --- Criterion 3: short-TTL cache + refetch after expiry --------------------
+test("two bad getTree within TTL share ONE /spaces fetch; a refetch happens after TTL", async () => {
+  const c = makeClient();
+  c.enumerateSpacePages = async () => {
+    throw make404();
+  };
+
+  await assert.rejects(() => c.getTree(BAD), /не найден среди/);
+  await assert.rejects(() => c.getTree(BAD), /не найден среди/);
+  assert.equal(c._spacesFetches, 1, "second call served from cache");
+
+  // Age the cache past the default 60s TTL -> exactly one refetch.
+  assert.ok(c.spaceIndexCache, "a complete result was cached");
+  c.spaceIndexCache.fetchedAt = Date.now() - 10 * 60 * 1000;
+  await assert.rejects(() => c.getTree(BAD), /не найден среди/);
+  assert.equal(c._spacesFetches, 2, "exactly one refetch after TTL");
+});
+
+// --- Criterion 4: no spaceId -> wrapper inert -------------------------------
+test("listPages WITHOUT spaceId is inert (raw error propagates, no /spaces sweep)", async () => {
+  const c = makeClient();
+  c.client.post = async () => {
+    throw make404("/pages/recent");
+  };
+  await assert.rejects(
+    () => c.listPages(),
+    (e) => {
+      assert.equal(e.response?.status, 404, "raw server 404 propagates");
+      assert.ok(!/не найден среди/.test(e.message ?? ""), "not rewritten");
+      return true;
+    },
+  );
+  assert.equal(c._spacesFetches, 0, "no /spaces sweep without a spaceId");
+});
+
+test("search WITHOUT spaceId is inert (raw error propagates, no /spaces sweep)", async () => {
+  const c = makeClient();
+  c.client.post = async () => {
+    throw make404("/search");
+  };
+  await assert.rejects(
+    () => c.search("query"),
+    (e) => {
+      assert.equal(e.response?.status, 404, "raw server 404 propagates");
+      assert.ok(!/не найден среди/.test(e.message ?? ""), "not rewritten");
+      return true;
+    },
+  );
+  assert.equal(c._spacesFetches, 0, "no /spaces sweep without a spaceId");
+});
+
+// --- Fail-open: a NON-404 error is never enriched (regression guard) --------
+test("a non-404 error (500) on a wrapped call propagates unchanged, with NO /spaces sweep", async () => {
+  const c = makeClient();
+  // A real server failure — must surface as-is, never be swallowed by the
+  // enrichment path or reformatted into a "not found among your spaces" message.
+  c.enumerateSpacePages = async () => {
+    throw makeAxiosErr(500, "/pages/tree", "Internal Server Error");
+  };
+  await assert.rejects(
+    () => c.getTree(BAD),
+    (e) => {
+      assert.equal(e.response?.status, 500, "the original 500 propagates");
+      assert.ok(
+        !/не найден среди/.test(e.message ?? ""),
+        "a non-404 is NOT rewritten",
+      );
+      return true;
+    },
+  );
+  assert.equal(c._spacesFetches, 0, "no /spaces sweep for a non-404");
+});
+
+// --- Fail-open: 404 when the spaceId IS accessible -> not about the space ----
+test("a 404 when the spaceId IS in the accessible index fails open (the 404 is about something else)", async () => {
+  const c = makeClient();
+  // The wrapped call 404s, but the spaceId is genuinely accessible — the 404
+  // must be about some OTHER resource, so the original error propagates and is
+  // NOT falsely rewritten to "spaceId not found among your spaces".
+  c.enumerateSpacePages = async () => {
+    throw make404();
+  };
+  await assert.rejects(
+    () => c.getTree(SPACES[0].id),
+    (e) => {
+      assert.equal(e.response?.status, 404, "original 404 preserved");
+      assert.ok(
+        !/не найден среди/.test(e.message ?? ""),
+        "no false 'not found' when the space is accessible",
+      );
+      return true;
+    },
+  );
+  assert.equal(c._spacesFetches, 1, "the index WAS consulted to make this call");
+});
+
+// --- Criterion 5: incomplete listing -> fail open ---------------------------
+test("a truncated /spaces listing (!complete) fails OPEN with the original 404", async () => {
+  const c = makeClient({ truncated: true });
+  c.enumerateSpacePages = async () => {
+    throw make404();
+  };
+  await assert.rejects(
+    () => c.getTree(BAD),
+    (e) => {
+      assert.equal(e.response?.status, 404, "original server error preserved");
+      assert.ok(!/не найден среди/.test(e.message ?? ""), "no false rewrite");
+      return true;
+    },
+  );
+  assert.equal(c.spaceIndexCache, null, "a truncated result is never cached");
+});
+
+// --- Criterion 6: /spaces fetch fails -> fail open; in-flight nulled on reject
+test("a /spaces fetch failure fails OPEN, logs under DEBUG, and never memoizes the rejected in-flight promise", async () => {
+  const c = makeClient();
+  let fetchCount = 0;
+  c.paginateAllWithMeta = async () => {
+    fetchCount++;
+    throw new Error("network boom");
+  };
+  c.enumerateSpacePages = async () => {
+    throw make404();
+  };
+
+  const prevDebug = process.env.DEBUG;
+  process.env.DEBUG = "1";
+  const errs = [];
+  const origErr = console.error;
+  console.error = (...a) => errs.push(a.map(String).join(" "));
+  try {
+    await assert.rejects(
+      () => c.getTree(BAD),
+      (e) => {
+        assert.equal(e.response?.status, 404, "original 404 rethrown");
+        return true;
+      },
+    );
+  } finally {
+    console.error = origErr;
+    if (prevDebug === undefined) delete process.env.DEBUG;
+    else process.env.DEBUG = prevDebug;
+  }
+
+  assert.ok(
+    errs.some((l) => l.includes("space-diag: /spaces fetch failed")),
+    "a DEBUG stderr line is emitted",
+  );
+  assert.equal(c.spaceIndexInFlight, null, "in-flight promise nulled on reject");
+
+  // The rejected in-flight promise must NOT be reused: a second enrichment does
+  // a genuinely fresh fetch (fetchCount increments to 2).
+  await assert.rejects(
+    () => c.getTree(BAD),
+    (e) => e.response?.status === 404,
+  );
+  assert.equal(fetchCount, 2, "fresh fetch — rejected promise not memoized");
+});
+
+// --- Criterion 7: zero accessible spaces ------------------------------------
+test("zero accessible spaces yields the dedicated 'no accessible spaces' message", async () => {
+  const c = makeClient({ spaces: [] });
+  c.enumerateSpacePages = async () => {
+    throw make404();
+  };
+  await assert.rejects(
+    () => c.getTree(BAD),
+    (e) => {
+      assert.ok(
+        e.message.includes("доступных тебе спейсов нет"),
+        "the zero-spaces branch fired",
+      );
+      assert.ok(e.message.includes(BAD), "still names the bad spaceId");
+      return true;
+    },
+  );
+});
+
+// --- Criterion 8: abort/cap during enrichment -------------------------------
+test("an aborted signal (custom/TimeoutError reason) propagates its reason, not a rewrite, and skips the sweep", async () => {
+  const c = makeClient();
+  const ac = new AbortController();
+  const reason = new Error("per-call cap exceeded");
+  reason.name = "TimeoutError"; // NOT 'AbortError' — hole B
+  ac.abort(reason);
+  c.setToolAbortSignal(ac.signal);
+  // Simulate paginateAll's throwIfAborted(): the inner op rejects with the
+  // signal's reason (not an AxiosError).
+  c.enumerateSpacePages = async () => {
+    throw ac.signal.reason;
+  };
+
+  await assert.rejects(
+    () => c.getTree(BAD),
+    (e) => {
+      assert.equal(e, reason, "the abort/cap reason itself propagates");
+      assert.equal(e.name, "TimeoutError");
+      assert.ok(!/не найден среди/.test(e.message ?? ""), "no rewrite");
+      return true;
+    },
+  );
+  assert.equal(c._spacesFetches, 0, "abort short-circuits before any sweep");
+});
+
+// --- Criterion 9: createPage is NOT wrapped (real offline server) -----------
+function readBody(req) {
+  return new Promise((resolve) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => resolve(raw));
+  });
+}
+function sendJson(res, status, obj, extra = {}) {
+  res.writeHead(status, { "Content-Type": "application/json", ...extra });
+  res.end(JSON.stringify(obj));
+}
+const openServers = [];
+function spawn(handler) {
+  return new Promise((resolve) => {
+    const server = http.createServer(handler);
+    server.listen(0, "127.0.0.1", () => {
+      openServers.push(server);
+      const { port } = server.address();
+      resolve({ baseURL: `http://127.0.0.1:${port}/api` });
+    });
+  });
+}
+after(async () => {
+  await Promise.all(openServers.map((s) => new Promise((r) => s.close(r))));
+});
+
+test("createPage with an inaccessible spaceId returns the server error as-is (NOT wrapped)", async () => {
+  const { baseURL } = await spawn(async (req, res) => {
+    await readBody(req);
+    if (req.url === "/api/auth/login") {
+      sendJson(res, 200, { success: true }, {
+        "Set-Cookie": "authToken=t; Path=/; HttpOnly",
+      });
+      return;
+    }
+    if (req.url === "/api/pages/import") {
+      // The space-permissions 404 createPage would see for a bad spaceId.
+      sendJson(res, 404, { message: "Space permissions not found" });
+      return;
+    }
+    sendJson(res, 404, {});
+  });
+
+  const client = new DocmostClient(baseURL, "u@example.com", "pw");
+  // Prove the diagnostics path is never entered from createPage.
+  let idxCalls = 0;
+  const realIdx = client.getAccessibleSpaceIndex.bind(client);
+  client.getAccessibleSpaceIndex = async () => {
+    idxCalls++;
+    return realIdx();
+  };
+
+  await assert.rejects(
+    () => client.createPage("Title", "body", BAD),
+    (e) => {
+      assert.equal(e.response?.status, 404, "the raw server 404 surfaces");
+      assert.ok(
+        !/не найден среди/.test(e.message ?? ""),
+        "createPage's 404 is NOT rewritten (multi-cause path)",
+      );
+      return true;
+    },
+  );
+  assert.equal(idxCalls, 0, "createPage never invokes the space diagnostics");
+});
+
+// --- formatSpaceNotAccessible unit shape ------------------------------------
+test("formatSpaceNotAccessible caps the inline list at 10 and appends a (+N ещё) tail", () => {
+  // Short ids/names so the whole message stays under the length cap and the full
+  // list-cap behaviour (first 10 shown, rest collapsed) is observable intact.
+  const many = Array.from({ length: 13 }, (_, i) => ({
+    id: `s${i}`,
+    name: `${i}`,
+  }));
+  const msg = formatSpaceNotAccessible("getTree", BAD, many);
+  assert.ok(msg.includes("s0 (0)"));
+  assert.ok(msg.includes("s9 (9)"), "10th entry (index 9) is shown");
+  assert.ok(!msg.includes("s10 (10)"), "the 11th is collapsed");
+  assert.ok(msg.includes("(+3 ещё, см. listSpaces)"), "tail counts the remainder");
+  assert.ok(msg.length <= 300, `short-name message stays under the cap (${msg.length})`);
+});
+
+test("formatSpaceNotAccessible caps the assembled message at ERROR_MESSAGE_CAP (300)", () => {
+  // 10 spaces with long names would, uncapped, produce a message several times
+  // over the 300-char budget. The cap must keep it compact while still carrying
+  // the bad spaceId and the listSpaces pointer.
+  const longName = "X".repeat(120);
+  const spaces = Array.from({ length: 10 }, (_, i) => ({
+    id: `id-${i}`,
+    name: `${longName}-${i}`,
+  }));
+  const msg = formatSpaceNotAccessible("getTree", BAD, spaces);
+  assert.ok(
+    msg.length <= 300,
+    `message must be <= 300 chars, got ${msg.length}`,
+  );
+  assert.ok(msg.includes(BAD), "the bad spaceId survives the cap");
+  assert.ok(msg.includes("listSpaces"), "the listSpaces pointer survives the cap");
+});