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

docs(reload-guard): align header/docstring wording to the window model (#481 review F2 consistency)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-12 05:36:59 +03:00 · 2026-07-12 05:36:58 +03:00 · 2026-07-12 05:32:33 +03:00 · 2026-07-12 05:01:36 +03:00 · 2026-07-12 04:55:22 +03:00 · 2026-07-12 04:55:22 +03:00
42 changed files with 1140 additions and 2089 deletions
@@ -463,6 +463,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, schema, `canonicalizeFootnotes`) — editor schema changes often need to be made in `editor-ext`, not just the client. Server-side markdown import/export no longer lives in `editor-ext`: it goes through the canonical converter (#345, see below). The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by `mcp`, `git-sync`, `apps/server` (#345), and `apps/client` (#347) — do NOT reintroduce a per-package copy. The client uses the package's `browser` entry (`@docmost/prosemirror-markdown/browser`): markdown paste (`markdown-clipboard.ts`), copy-as-markdown, and AI-chat rendering now all go through the canonical converter, so the hand-written `marked`/`turndown` markdown layer that used to live in `editor-ext` was deleted (#347). The browser entry runs the HTML→DOM stage on the native `DOMParser`, so jsdom stays out of the client bundle. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence. For the converter's property-testing and counterexample→fixture process (P1–P4 invariants, the `PROPERTY_SEED`/`PROPERTY_NUM_RUNS` knobs, and the nightly fuzz workflow), see `packages/prosemirror-markdown/README.md`.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
+- The build also emits `client/dist/version.json` (`{"version": …}`) from a small `vite.config.ts` plugin using the **same** `appVersion` that feeds `define.APP_VERSION`, so the file and the baked-in bundle version are identical by construction. The server reads it at startup (`ws.gateway.ts` via `readClientBuildVersion`/`resolveClientDistPath`) and announces it to each socket on connect (`app-version` event) so a tab left open across a redeploy can guard-reload before hitting a stale chunk (version-coherence). No runtime env / Dockerfile change — the file already ships in `client/dist`; missing/empty file ⇒ feature inert.

 ## Conventions

@@ -142,6 +142,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  snapshots switched from a fixed interval to a trailing idle-flush with a
  max-wait ceiling, and a boundary snapshot is pinned whenever the editing source
  changes (e.g. a person's edits followed by the AI agent). (#370)
+- **Open tabs pick up a new deploy on their own.** After the server is
+  redeployed while a tab is left open for hours, the tab now learns the new
+  build version over the existing WebSocket (announced per-connect, so a natural
+  reconnect delivers it) and shows a "A new version is available" banner with an
+  Update button. To avoid dropping a half-written comment or form, the tab is
+  not reloaded when you merely switch away from it; instead it auto-reloads at
+  the next safe point — the next in-app navigation (or immediately if you click
+  Update) — before it can hit a stale lazy-loaded chunk. At most one automatic
+  reload happens per 5-minute window, shared with the existing chunk-load
+  recovery, so a permanent version skew degrades to the banner rather than a
+  reload loop while a second deploy in the same tab still recovers. When the
+  build carries no version info the feature stays inert. (#481)

 - **Place several images side by side in a row.** A new "Inline (side by
  side)" alignment mode in the image bubble menu renders consecutive inline
@@ -1,4 +1,5 @@
 {
+  "A new version is available": "A new version is available",
  "Account": "Account",
  "Active": "Active",
  "Add": "Add",
@@ -1427,20 +1428,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."
 }
@@ -1,4 +1,5 @@
 {
+  "A new version is available": "Доступна новая версия",
  "Account": "Аккаунт",
  "Active": "Активный",
  "Add": "Добавить",
@@ -1442,20 +1443,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.": "Пока нет сохранённых версий."
 }
@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { isChunkLoadError, shouldAutoReload } from "./chunk-load-error-boundary";
+import { isChunkLoadError } from "./chunk-load-error-boundary";

 // The detector decides whether a caught render error is a stale-deploy chunk-404
 // (→ auto-reload to fetch the new manifest) vs a genuine app error (→ generic
@@ -35,31 +35,3 @@ describe("isChunkLoadError", () => {
    expect(isChunkLoadError(err)).toBe(false);
  });
 });
-
-// The window gate replaces the old one-shot flag: it must permit recovery across
-// several deploys in one tab (each > window apart) while still stopping an infinite
-// reload loop when a lazy chunk is permanently broken (a second failure < window).
-describe("shouldAutoReload", () => {
-  const WINDOW = 5 * 60 * 1000;
-  const NOW = 1_000_000_000_000;
-
-  it("allows a reload when we have never auto-reloaded", () => {
-    expect(shouldAutoReload(NOW, null, WINDOW)).toBe(true);
-  });
-
-  it("allows a reload when the last one was 6 minutes ago (outside the window)", () => {
-    expect(shouldAutoReload(NOW, NOW - 6 * 60 * 1000, WINDOW)).toBe(true);
-  });
-
-  it("blocks a reload when the last one was 1 minute ago (inside the window)", () => {
-    expect(shouldAutoReload(NOW, NOW - 1 * 60 * 1000, WINDOW)).toBe(false);
-  });
-
-  it("blocks a reload exactly at the window boundary (not strictly older)", () => {
-    expect(shouldAutoReload(NOW, NOW - WINDOW, WINDOW)).toBe(false);
-  });
-
-  it("allows a reload when the stored timestamp is unparseable (NaN)", () => {
-    expect(shouldAutoReload(NOW, NaN, WINDOW)).toBe(true);
-  });
-});
@@ -1,26 +1,11 @@
 import { ReactNode } from "react";
 import { ErrorBoundary } from "react-error-boundary";
 import { Button, Center, Stack, Text } from "@mantine/core";
-
-// sessionStorage key holding the epoch-ms timestamp of the last automatic reload.
-const RELOAD_AT_KEY = "chunk-reload-at";
-// Allow at most one automatic reload per this window. A stale-deploy 404 is cured
-// by a single reload, so anything inside the window is treated as a reload loop
-// (permanently-broken chunk) and falls through to the manual UI. A window (rather
-// than a one-shot flag) lets a SECOND deploy in the same tab's lifetime recover too.
-const RELOAD_WINDOW_MS = 5 * 60 * 1000;
-
-// Pure window decision, unit-tested in isolation: auto-reload only if we have never
-// auto-reloaded (lastReloadAt null/NaN) or the last one was strictly older than the
-// window. Anything inside the window is suppressed to break an infinite reload loop.
-export function shouldAutoReload(
-  now: number,
-  lastReloadAt: number | null,
-  windowMs: number,
-): boolean {
-  if (lastReloadAt === null || Number.isNaN(lastReloadAt)) return true;
-  return now - lastReloadAt > windowMs;
-}
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  recordReloadBreadcrumb,
+} from "@/lib/reload-guard";

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

-function handleError(error: unknown) {
+// Exported for tests: the reactive chunk-load reload decision, so the shared
+// window budget (invariant: ≤1 auto-reload per window across this path AND the
+// proactive version-coherence path) can be exercised against the real guard.
+export function handleError(error: unknown) {
  if (!isChunkLoadError(error)) return;
  // A stale-chunk 404 is cured by a full reload that re-fetches index.html and
-  // the new chunk manifest. Auto-reload at most once per RELOAD_WINDOW_MS: this
-  // recovers across multiple deploys in a single tab's lifetime, yet a
-  // permanently-broken lazy chunk (which would loop) is stopped after the first
-  // reload and falls through to the manual recovery UI below.
-  try {
-    const raw = sessionStorage.getItem(RELOAD_AT_KEY);
-    const lastReloadAt = raw === null ? null : Number.parseInt(raw, 10);
-    const now = Date.now();
-    if (!shouldAutoReload(now, lastReloadAt, RELOAD_WINDOW_MS)) return;
-    sessionStorage.setItem(RELOAD_AT_KEY, String(now));
-  } catch {
-    // sessionStorage unavailable (private mode / disabled): skip the automatic
-    // reload rather than risk an unguarded loop; the fallback UI still recovers.
-    return;
-  }
+  // the new chunk manifest. Auto-reload at most once per window via the SHARED
+  // window-based reload guard (see @/lib/reload-guard — the same budget the
+  // proactive version-coherence path consumes, so a mismatch that arrives on
+  // both paths reloads at most once per window across BOTH). This recovers
+  // across multiple deploys in a single tab's lifetime, yet a permanently-broken
+  // lazy chunk (which would loop) is stopped after the first reload and falls
+  // through to the manual recovery UI below. If the shared budget is already
+  // spent this window, or the stamp write fails (storage unavailable), we return
+  // without reloading rather than risk a loop.
+  if (hasAutoReloaded()) return;
+  if (!markAutoReloaded()) return;
+  // Trace before the reload clears the console (same diagnostic breadcrumb the
+  // proactive version-coherence path writes, tagged with this path).
+  recordReloadBreadcrumb({ path: "chunk-boundary" });
  window.location.reload();
 }

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

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

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

+    // Register the version-coherence listener SYNCHRONOUSLY, before the socket
+    // connects: the server emits `app-version` immediately in handleConnection,
+    // so a listener attached after connect would miss it on a fast localhost
+    // connect. On a version mismatch the client shows a banner and defers the
+    // auto-reload to the next in-app navigation (variant C — avoids reloading a
+    // backgrounded tab that may hold unsaved input) before it hits a stale chunk.
+    newSocket.on("app-version", (payload?: AppVersionSocketPayload) => {
+      triggerGuardedReload(payload?.version);
+    });
+
    return () => {
      console.log("ws disconnected");
      newSocket.disconnect();
@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { decideVersionAction } from "./version-coherence";
+
+describe("decideVersionAction", () => {
+  it("noop when the server version is empty (fail-safe)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "",
+        clientVersion: "v1",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("noop when the client version is empty (fail-safe)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("noop when versions are equal (in sync)", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "v1",
+        autoReloadUsed: false,
+      }),
+    ).toBe("noop");
+  });
+
+  it("reload on a real mismatch the first time this session", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "test-B",
+        clientVersion: "test-A",
+        autoReloadUsed: false,
+      }),
+    ).toBe("reload");
+  });
+
+  it("banner on a mismatch once the session auto-reload is spent", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "test-B",
+        clientVersion: "test-A",
+        autoReloadUsed: true,
+      }),
+    ).toBe("banner");
+  });
+
+  it("equal versions stay noop even if auto-reload was already used", () => {
+    expect(
+      decideVersionAction({
+        serverVersion: "v1",
+        clientVersion: "v1",
+        autoReloadUsed: true,
+      }),
+    ).toBe("noop");
+  });
+});
@@ -0,0 +1,32 @@
+// Payload of the per-connect `app-version` socket.io event announced by the
+// server (ws.gateway.ts) after a successful auth. A dedicated event — NOT a
+// member of the room-scoped `WebSocketEvent` union (which is discriminated by
+// `operation`), so it never touches use-query-subscription.
+export type AppVersionSocketPayload = { version: string };
+
+/**
+ * Pure decision for the version-coherence guard.
+ *
+ * All inputs are injected (no globals, no side effects) so it is unit-testable
+ * without a DOM or the build-time `APP_VERSION` global (undefined under vitest).
+ *
+ * - `autoReloadUsed` = an automatic reload has already happened within the
+ *   current ~5-min window, so we must not auto-reload again (loop safety,
+ *   shared window budget with the reactive chunk-load boundary).
+ *
+ * Returns:
+ * - "noop"   — do nothing (unknown version on either side, or already in sync).
+ * - "banner" — show the manual "update available" banner only (no auto-reload).
+ * - "reload" — real first-time mismatch: eligible for a guarded auto-reload.
+ */
+export function decideVersionAction(args: {
+  serverVersion: string;
+  clientVersion: string;
+  autoReloadUsed: boolean;
+}): "reload" | "banner" | "noop" {
+  const { serverVersion, clientVersion, autoReloadUsed } = args;
+  if (!serverVersion || !clientVersion) return "noop"; // fail-safe: unknown version → never act
+  if (serverVersion === clientVersion) return "noop"; // in sync
+  if (autoReloadUsed) return "banner"; // one auto-reload per RELOAD_WINDOW_MS window already spent
+  return "reload"; // real mismatch, window budget available
+}
@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  hasAutoReloaded,
+  markAutoReloaded,
+  shouldAutoReload,
+  recordReloadBreadcrumb,
+  takeReloadBreadcrumb,
+  RELOAD_WINDOW_MS,
+} from "./reload-guard";
+
+// The shared budget is a single sessionStorage timestamp keyed here; both the
+// reactive chunk-load boundary and the proactive version-coherence path read and
+// stamp it, so at most one auto-reload happens per RELOAD_WINDOW_MS across BOTH.
+const RELOAD_AT_KEY = "chunk-reload-at";
+const NOW = 1_000_000_000_000;
+
+describe("reload-guard", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("hasAutoReloaded is false before any reload, true within the window after mark", () => {
+    expect(hasAutoReloaded(NOW)).toBe(false);
+    expect(markAutoReloaded(NOW)).toBe(true);
+    // Same key both paths share; stores the reload timestamp, not a flag.
+    expect(sessionStorage.getItem(RELOAD_AT_KEY)).toBe(String(NOW));
+    // Inside the window → budget spent → true (fall through to manual UI).
+    expect(hasAutoReloaded(NOW)).toBe(true);
+    expect(hasAutoReloaded(NOW + RELOAD_WINDOW_MS)).toBe(true);
+  });
+
+  it("hasAutoReloaded is false again once the window has elapsed (a later deploy recovers)", () => {
+    markAutoReloaded(NOW);
+    // Strictly older than the window → a new deploy's mismatch may reload again.
+    expect(hasAutoReloaded(NOW + RELOAD_WINDOW_MS + 1)).toBe(false);
+  });
+
+  it("hasAutoReloaded returns true when reading storage throws (fail toward not reloading)", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => {
+        throw new Error("storage disabled");
+      },
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+    });
+    try {
+      expect(hasAutoReloaded()).toBe(true);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("hasAutoReloaded treats an unparseable stored timestamp as never-reloaded", () => {
+    sessionStorage.setItem(RELOAD_AT_KEY, "not-a-number");
+    expect(hasAutoReloaded(NOW)).toBe(false);
+  });
+
+  it("markAutoReloaded returns false when writing storage throws", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+    });
+    try {
+      expect(markAutoReloaded()).toBe(false);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("records and then takes a breadcrumb once (cleared on read)", () => {
+    recordReloadBreadcrumb({
+      path: "proactive",
+      serverVersion: "test-B",
+      clientVersion: "test-A",
+    });
+    const crumb = takeReloadBreadcrumb();
+    expect(crumb).toMatchObject({
+      path: "proactive",
+      serverVersion: "test-B",
+      clientVersion: "test-A",
+    });
+    expect(typeof crumb?.at).toBe("number");
+    // Cleared on read → a second take returns null.
+    expect(takeReloadBreadcrumb()).toBeNull();
+  });
+
+  it("takeReloadBreadcrumb returns null when nothing was recorded", () => {
+    expect(takeReloadBreadcrumb()).toBeNull();
+  });
+
+  it("recordReloadBreadcrumb swallows a storage-write error (diagnostics only)", () => {
+    vi.stubGlobal("sessionStorage", {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("storage disabled");
+      },
+      removeItem: () => {},
+    });
+    try {
+      expect(() =>
+        recordReloadBreadcrumb({ path: "chunk-boundary" }),
+      ).not.toThrow();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+// The pure window gate replaces the old one-shot flag: it must permit recovery
+// across several deploys in one tab (each > window apart) while still stopping an
+// infinite reload loop when a lazy chunk is permanently broken (a second failure
+// < window). Moved here from the chunk-load boundary now that it is the shared
+// guard both paths route through.
+describe("shouldAutoReload", () => {
+  const WINDOW = RELOAD_WINDOW_MS;
+
+  it("allows a reload when we have never auto-reloaded", () => {
+    expect(shouldAutoReload(NOW, null, WINDOW)).toBe(true);
+  });
+
+  it("allows a reload when the last one was 6 minutes ago (outside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 6 * 60 * 1000, WINDOW)).toBe(true);
+  });
+
+  it("blocks a reload when the last one was 1 minute ago (inside the window)", () => {
+    expect(shouldAutoReload(NOW, NOW - 1 * 60 * 1000, WINDOW)).toBe(false);
+  });
+
+  it("blocks a reload exactly at the window boundary (not strictly older)", () => {
+    expect(shouldAutoReload(NOW, NOW - WINDOW, WINDOW)).toBe(false);
+  });
+
+  it("allows a reload when the stored timestamp is unparseable (NaN)", () => {
+    expect(shouldAutoReload(NOW, NaN, WINDOW)).toBe(true);
+  });
+});
@@ -0,0 +1,121 @@
+// Shared, window-based auto-reload budget.
+//
+// Both auto-reload paths — the reactive chunk-load-error-boundary (recovers
+// AFTER a stale lazy chunk 404s) and the proactive version-coherence feature
+// (reloads BEFORE the tab hits a stale chunk) — go through these functions so
+// they share ONE window-scoped reload budget: at most a single automatic
+// reload per RELOAD_WINDOW_MS across BOTH paths. A window (rather than a
+// permanent one-shot flag) lets a SECOND deploy in the same tab's lifetime
+// recover too, while a permanent skew, node oscillation, or a genuinely-missing
+// chunk still degrades to a manual banner/UI after the first reload instead of
+// looping. When sessionStorage is unavailable every mismatch degrades to the
+// manual UI — no unguarded reload.
+
+// sessionStorage key holding the epoch-ms timestamp of the last automatic reload
+// (shared by both paths).
+const RELOAD_AT_KEY = "chunk-reload-at";
+
+// Allow at most one automatic reload per this window. A stale-deploy 404 is cured
+// by a single reload, so anything inside the window is treated as a reload loop
+// (permanently-broken chunk / permanent skew) and falls through to the manual UI.
+export const RELOAD_WINDOW_MS = 5 * 60 * 1000;
+
+/**
+ * Pure window decision, unit-tested in isolation: auto-reload only if we have
+ * never auto-reloaded (lastReloadAt null/NaN) or the last one was strictly older
+ * than the window. Anything inside the window is suppressed to break an infinite
+ * reload loop.
+ */
+export function shouldAutoReload(
+  now: number,
+  lastReloadAt: number | null,
+  windowMs: number,
+): boolean {
+  if (lastReloadAt === null || Number.isNaN(lastReloadAt)) return true;
+  return now - lastReloadAt > windowMs;
+}
+
+/**
+ * Has an automatic reload already happened within the current window (so the
+ * shared budget is spent right now)? Both paths check this before reloading; a
+ * `true` return means fall through to the manual banner/UI instead of reloading.
+ *
+ * A storage read error (private mode / disabled) is reported as `true` so the
+ * caller fails toward NOT reloading — an unguarded loop is worse than a stale
+ * tab the user can reload manually. Note a window (not a permanent flag): once
+ * the window elapses a later deploy's mismatch is allowed to reload again.
+ */
+export function hasAutoReloaded(now: number = Date.now()): boolean {
+  try {
+    const raw = sessionStorage.getItem(RELOAD_AT_KEY);
+    const lastReloadAt = raw === null ? null : Number.parseInt(raw, 10);
+    return !shouldAutoReload(now, lastReloadAt, RELOAD_WINDOW_MS);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Stamp the shared window as consumed now — record that an automatic reload is
+ * being performed within the current RELOAD_WINDOW_MS window.
+ *
+ * Returns whether the write succeeded. A `false` return (storage unavailable)
+ * means the caller MUST NOT reload — otherwise the stamp would never stick and
+ * the reload could loop.
+ */
+export function markAutoReloaded(now: number = Date.now()): boolean {
+  try {
+    sessionStorage.setItem(RELOAD_AT_KEY, String(now));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Diagnostic breadcrumb for an automatic reload. Written right before
+// window.location.reload() (which clears the console) and read back on the next
+// page load, so a "the tab reloaded itself / it's looping" field report is
+// diagnosable: which path fired (proactive version-coherence vs the reactive
+// chunk-load boundary) and which version pair triggered it. sessionStorage
+// survives a same-tab reload, unlike the console.
+const RELOAD_BREADCRUMB_KEY = "reload-breadcrumb";
+
+export type ReloadBreadcrumb = {
+  path: "proactive" | "chunk-boundary";
+  serverVersion?: string;
+  clientVersion?: string;
+  at: number;
+};
+
+/**
+ * Persist a best-effort breadcrumb just before an automatic reload. Failures
+ * (storage unavailable) are swallowed — this is diagnostics only and must never
+ * block or alter the reload decision.
+ */
+export function recordReloadBreadcrumb(
+  entry: Omit<ReloadBreadcrumb, "at">,
+): void {
+  try {
+    sessionStorage.setItem(
+      RELOAD_BREADCRUMB_KEY,
+      JSON.stringify({ ...entry, at: Date.now() }),
+    );
+  } catch {
+    // best-effort diagnostics only
+  }
+}
+
+/**
+ * Read and clear the breadcrumb left by an auto-reload in the previous page
+ * load. Cleared on read so it surfaces exactly once per reload.
+ */
+export function takeReloadBreadcrumb(): ReloadBreadcrumb | null {
+  try {
+    const raw = sessionStorage.getItem(RELOAD_BREADCRUMB_KEY);
+    if (!raw) return null;
+    sessionStorage.removeItem(RELOAD_BREADCRUMB_KEY);
+    return JSON.parse(raw) as ReloadBreadcrumb;
+  } catch {
+    return null;
+  }
+}
@@ -1,7 +1,8 @@
-import { defineConfig, loadEnv } from "vite";
+import { defineConfig, loadEnv, type Plugin } from "vite";
 import react from "@vitejs/plugin-react";
 import { compression } from "vite-plugin-compression2";
 import * as path from "path";
+import * as fs from "node:fs";
 import { execSync } from "node:child_process";

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

+// Emit <outDir>/version.json = { "version": appVersion } so the server can read
+// the exact same build id the bundle was compiled with. The value is the SAME
+// `appVersion` fed into `define.APP_VERSION`, so version.json and the baked-in
+// global are identical by construction — the single source of truth (no
+// runtime-env second copy that could drift and cause a false version mismatch).
+function versionJsonPlugin(version: string): Plugin {
+  let outDir = "dist";
+  return {
+    name: "emit-version-json",
+    apply: "build",
+    configResolved(config) {
+      outDir = config.build.outDir;
+    },
+    writeBundle() {
+      const root = path.resolve(process.cwd(), outDir);
+      fs.mkdirSync(root, { recursive: true });
+      fs.writeFileSync(
+        path.join(root, "version.json"),
+        JSON.stringify({ version }),
+      );
+    },
+  };
+}
+
 export default defineConfig(({ mode }) => {
+  const appVersion = resolveAppVersion(envPath);
  const {
    APP_URL,
    FILE_UPLOAD_SIZE_LIMIT,
@@ -52,10 +78,11 @@ export default defineConfig(({ mode }) => {
        POSTHOG_HOST,
        POSTHOG_KEY,
      },
-      APP_VERSION: JSON.stringify(resolveAppVersion(envPath)),
+      APP_VERSION: JSON.stringify(appVersion),
    },
    plugins: [
      react(),
+      versionJsonPlugin(appVersion),
      // Emit .br and .gz next to every built asset so the server can serve the
      // precompressed copy (see @fastify/static preCompressed in static.module.ts).
      compression({
@@ -0,0 +1,52 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import { readClientBuildVersion } from './client-version';
+
+describe('readClientBuildVersion', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(join(os.tmpdir(), 'client-version-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const writeVersionJson = (content: string) =>
+    fs.writeFileSync(join(dir, 'version.json'), content);
+
+  it('returns the version from a valid version.json', () => {
+    writeVersionJson(JSON.stringify({ version: 'test-A' }));
+    expect(readClientBuildVersion(dir)).toBe('test-A');
+  });
+
+  it('trims surrounding whitespace in the version', () => {
+    writeVersionJson(JSON.stringify({ version: '  v1.2.3  ' }));
+    expect(readClientBuildVersion(dir)).toBe('v1.2.3');
+  });
+
+  it('returns "" when version.json is missing', () => {
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" on malformed JSON', () => {
+    writeVersionJson('{ not json');
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is absent', () => {
+    writeVersionJson(JSON.stringify({ notVersion: 'x' }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the version field is not a string', () => {
+    writeVersionJson(JSON.stringify({ version: 123 }));
+    expect(readClientBuildVersion(dir)).toBe('');
+  });
+
+  it('returns "" when the path does not exist at all', () => {
+    expect(readClientBuildVersion(join(dir, 'nope'))).toBe('');
+  });
+});
@@ -0,0 +1,36 @@
+import { join } from 'path';
+import * as fs from 'node:fs';
+
+/**
+ * Resolve the absolute path to the built client bundle directory
+ * (`apps/client/dist`) shipped into the runtime image.
+ *
+ * The `../` depth is anchored on THIS module's compiled location
+ * (`dist/common/helpers`). `integrations/static` sits at the same depth under
+ * the compiled root, so both callers (StaticModule and readClientBuildVersion)
+ * MUST share this single helper rather than duplicating the depth — a copy in a
+ * module at a different depth would silently resolve to the wrong directory.
+ */
+export function resolveClientDistPath(): string {
+  return join(__dirname, '..', '..', '..', '..', 'client/dist');
+}
+
+/**
+ * Read the build version the client bundle was compiled with, from
+ * `<clientDistPath>/version.json` (written by the Vite build — the single
+ * source of truth shared by the baked-in `APP_VERSION` global and this file).
+ *
+ * Fail-safe: any error (missing file, unreadable, bad JSON, non-string
+ * version) yields `''`. The caller treats an empty version as "unknown" and
+ * the whole version-coherence feature stays silently inert — existing deploys
+ * without the file keep working unchanged.
+ */
+export function readClientBuildVersion(clientDistPath: string): string {
+  try {
+    const raw = fs.readFileSync(join(clientDistPath, 'version.json'), 'utf8');
+    const version = (JSON.parse(raw) as { version?: unknown }).version;
+    return typeof version === 'string' ? version.trim() : '';
+  } catch {
+    return '';
+  }
+}
@@ -3,3 +3,4 @@ export * from './nanoid.utils';
 export * from './file.helper';
 export * from './constants';
 export * from './security-headers';
+export * from './client-version';
@@ -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()
@@ -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');
-    });
-  });
 });
@@ -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(
@@ -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,
-    };
-  }
 }
@@ -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));
-  });
-});
@@ -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;
-}
@@ -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);
-    }
-  });
-});
@@ -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,
-  };
-}
@@ -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';
@@ -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;
-}
@@ -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[];
-}
@@ -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?: {
@@ -4,6 +4,7 @@ import { join } from 'path';
 import * as fs from 'node:fs';
 import fastifyStatic from '@fastify/static';
 import { EnvironmentService } from '../environment/environment.service';
+import { resolveClientDistPath } from '../../common/helpers/client-version';

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

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

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

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

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

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

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

      client.join([userRoom, workspaceRoom, ...spaceRooms]);
+
+      // Announce this container's client build version to the freshly
+      // authenticated socket. On a redeploy the client reconnects to the new
+      // container and receives the new version here, letting it guard-reload
+      // before it hits a stale lazy chunk. Per-connect only (no broadcast):
+      // natural reconnect covers both single-container and cluster without a
+      // thundering-herd fleet reload.
+      client.emit('app-version', { version: this.appVersion });
    } catch (err) {
      client.emit('Unauthorized');
      client.disconnect();
@@ -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([]);
-  });
-});
Author	SHA1	Message	Date
agent_coder	b3cc6a7ff8	Merge remote-tracking branch 'gitea/develop' into feat/481-version-coherence	2026-07-12 05:36:59 +03:00
agent_coder	c42cb42413	docs(reload-guard): align header/docstring wording to the window model (#481 review F2 consistency) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 05:36:58 +03:00
agent_coder	41030b2c78	test+docs(deploy): покрыть reactive fail-closed guard + выровнять формулировки под оконный бюджет (#499 ревью) F1: интеграционный тест на reactive путь при storage, который ЧИТАЕТ, но не ПИШЕТ (quota / Safari private): getItem→null (бюджет доступен, проходим hasAutoReloaded), setItem→throw → markAutoReloaded()===false → guard на chunk-load-error-boundary.tsx:43 обязан отбить reload, иначе реактивный путь зациклил бы reload без сохранённого бюджета. Симметричный proactive случай уже покрыт guarded-reload.test.tsx. Мутация (снять guard :43) → тест краснеет. F2: формулировки "per session / this session" в version-coherence.ts и guarded-reload.tsx приведены к оконной модели ("per RELOAD_WINDOW_MS window" / "window budget available") — reload-guard.ts и тест восстановления после окна уже описывают именно окно, а не постоянный one-shot на сессию. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 05:32:33 +03:00
agent_coder	64566e9327	test(deploy): согласовать reload-guard/chunk-load тесты с общим оконным бюджетом (#481 , rebase reconcile) После ребейза на develop версии-когерентность (#481, общий one-shot флаг) и chunk-load boundary (#495, оконный guard) были сведены к ОДНОМУ общему оконному бюджету в @/lib/reload-guard: не более одного авто-reload за RELOAD_WINDOW_MS суммарно по обоим путям, при этом второй деплой в той же вкладке восстанавливается. - reload-guard.test.ts: переписаны под оконную семантику (ключ chunk-reload-at хранит таймстамп, а не флаг); сюда же перенесены чистые тесты shouldAutoReload. - chunk-load-error-boundary.test.ts: убран импорт shouldAutoReload (переехал в reload-guard). - chunk-load-error-boundary.tsx: handleError экспортирован для теста инварианта. - reload-budget.integration.test.tsx: инвариант (a) на РЕАЛЬНОМ guard — reload на одном пути тратит общий бюджет для другого в пределах окна, после окна восстановление, при недоступном sessionStorage ни один путь не перезагружает. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 05:01:36 +03:00
agent_coder	10a4326fbf	docs(deploy): поправить устаревший коммент про auto-reload скрытой вкладки под вариант C (#481 , ревью F1) r1-коммент утверждал «auto-reload on a hidden tab», но вариант C (r2) убрал авто-reload скрытой вкладки ради защиты несохранённого ввода. Переписал под фактическое поведение: баннер + отложенный reload на следующей in-app навигации. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 04:55:22 +03:00
agent_coder	68409a8ae9	fix(deploy): variant C — reload по in-app навигации вместо visibilitychange + лог-след + CHANGELOG (#481 , ревью) Правки по ревью #499. Владелец выбрал вариант C по вопросу потери несохранённого ввода. F1 (reload по навигации): убрал ветку visibilitychange→reload И немедленный reload скрытой-при-получении вкладки — visibility больше не влияет на авто-reload вообще. На реальном mismatch: баннер (кнопка «Обновить» — немедленный reload под тем же one-shot гардом) + модульный флаг pendingNavReload. Хук useVersionReloadOnNavigation (useLocation + useEffect по location.key, пропуск первого рендера через useRef; react-router v7 BrowserRouter компонентный, объекта роутера нет — подписка изнутри дерева) на СЛЕДУЮЩЕЙ навигации зовёт consumeNavigationReload → performAutoReload (mark-перед-reload, при spent/непишущемся storage — только баннер). Скрытая вкладка идёт тем же путём (C единообразно). chunk-load-error-boundary reload не тронут — остаётся бэкапом для не-навигирующей вкладки. Так reload в безопасной точке (юзер и так уходит со страницы), а не когда свернул с недописанным комментарием. F2 (лог-след): общий recordReloadBreadcrumb/takeReloadBreadcrumb (sessionStorage, переживает reload). performAutoReload пишет breadcrumb {path:proactive,server, client} + console.warn перед reload; chunk-boundary пишет {path:chunk-boundary}; surfacePreviousReloadBreadcrumb на маунте UserProvider логирует прошлый след. F3 (CHANGELOG + AGENTS.md): user-facing запись про version-coherence + строка про артефакт client/dist/version.json. Тесты: vitest version-coherence+reload-guard+guarded-reload 23 (переписан на MemoryRouter+useNavigate: reload РОВНО раз на первой навигации после mismatch, НЕ на 2-й навигации, НЕ на 2-м mismatch one-shot, НЕ от ухода в фон; скрытая вкладка — только на навигации; Update — сразу; banner-only/write-fail — никогда). Шире: features/user 34. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 04:55:22 +03:00
agent_coder	fc624f5a4b	feat(deploy): version-coherence — WS-анонс версии сервера + guarded reload устаревших вкладок (#481 ) SPA — долгоживущий клиент: вкладку держат часами, сервер за это время передеплоивают. Старый index.html ссылается на content-hashed чанки, которых в новом образе нет → ленивый import() → catch-all отдаёт index.html как text/html → WebKit «not a valid JavaScript MIME type» (наблюдали в проде). Реактивный предохранитель (chunk-error-boundary) ловит УЖЕ случившуюся ошибку. Делаем сигнал ПРОАКТИВНЫМ: сервер сообщает версию по существующему WS, клиент сравнивает и делает guarded reload ДО битого чанка. closes #481 - Единый источник версии: vite.config.ts вычисляет resolveAppVersion РОВНО раз → и в define.APP_VERSION, и в плагине, пишущем dist/version.json. Бандл и файл тождественны by construction. Сервер читает client/dist/version.json при старте (client-version.ts: resolveClientDistPath вынесен из static.module — единый источник пути; readClientBuildVersion → версия или '' на любой ошибке, fail-safe). НИКАКИХ Docker/ENV-изменений. - WS: отдельное событие app-version {version} (НЕ в message/WebSocketEvent — член без operation сломал бы union). ws.gateway читает версию в onModuleInit + boot-лог ACTIVE/DISABLED; emit в handleConnection (success-ветка, после join). ТОЛЬКО per-connect анонс, БЕЗ broadcast (broadcast в кластере → thundering-herd reload флота; естественный реконнект покрывает и single-container, и кластер). - Клиент: listener навешан СИНХРОННО в том же useEffect, что создаёт сокет (до connect — иначе гонка с немедленным emit сервера). Чистая decideVersionAction (reload\|banner\|noop; пустая версия → noop fail-safe). Грязная оболочка triggerGuardedReload: модульный latch, hidden→немедленный reload, visible→баннер + reload-on-hidden {once}, фикс-id закрываемый баннер с кнопкой «Обновить». - Общий one-shot флаг: reload-guard.ts (hasAutoReloaded/markAutoReloaded над существующим chunk-reload-attempted); chunk-load-error-boundary переведён на него. Проактивный + реактивный reload делят ОДИН счётчик → максимум одна авто-перезагрузка за сессию суммарно; permanent skew / oscillation / disabled storage → после первого reload только баннер, петли нет (проверено трассировкой). Проверка: server jest client-version 7/7; client vitest version-coherence+ reload-guard+guarded-reload 16/16 (coverage 97.9%). Build-proof единого источника: APP_VERSION=test-A → dist/version.json {"version":"test-A"} + вшито в бандл. Полный staging-приём (docker build-arg, WS-кадры в DevTools, мульти-таб) — вне автостенда, шаги приёмки #481 (крит.1-4) на ручную проверку. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-12 04:54:35 +03:00