feat(storage): first-class data - no silent failures in the persistence pipeline

The "Saved" label in the top bar used to be a comforting lie:
several failure modes (createRepo 403 on a missing manage-repos
scope, writeFileSync on a readonly FS, uploadFile mid-debounce
network blip) all collapsed into a console.error that the editor
never surfaced. A user could type for an hour, see "Saved" the
whole time, lose their tab, and discover only after the container
rebuilt that nothing had ever made it to the dataset.

Make every link in the chain observable, and make the worst signal
always win in the UI.

Backend
-------
- In-memory `StorageStatus` tracker in hf-storage.ts:
- `datasetReady` (createRepo succeeded or returned 409)
- `lastLocalSaveAt` / `lastCloudPushAt` epoch ms
- `pendingPush` (a debounce timer is armed)
- `lastError {stage, message, statusCode, at, docName}` where
`stage` is one of `dataset-create | local-save | cloud-push`
Every write path records success; every error path records the
failure. Success on one stage clears the error for THAT stage
only, so a cloud-push recovery doesn't paper over an underlying
dataset-create issue.
- `recordLocalSaveError` is called from persistence.ts so a
failed writeFileSync (disk full, readonly FS, perms) doesn't
evaporate. The previous catch logged and moved on - the new
one logs AND surfaces.
- `pushDocument` now decorates the error log with the HTTP status
for triage, AND pushes a structured record into the tracker.
- New route `GET /api/storage/status` returns the tracker. Gated
to canEdit so anonymous viewers never see dataset names /
error details. Cheap (in-memory map, no I/O).
- New route `GET /api/admin/export-doc?name=<doc>` streams the
on-disk `.yjs` snapshot to the caller as a date-stamped
download. Same canEdit gate. This is the disaster-recovery
escape hatch: when the cloud push has been failing and the
container is about to rebuild, an admin grabs the bytes
manually instead of relying on Dev Mode SSH.
- Eager `ensureDatasetExists` in `/api/auth/status` for canEdit
users. Before: a misconfigured fork looked perfectly healthy
for 12+ seconds (until the first edit's debounce window
closed). Now: the error lands in the tracker within ~1s of
login, and the next SyncIndicator poll (5s) flashes the red
badge with the exact reason in the tooltip.

Frontend
--------
- SyncIndicator rebuilt as a three-state badge:
- 🟢 saved WS connected + tracker green
- 🟡 pending local edit in flight OR backend push armed
- ⚫ offline WS disconnected (network or container restart)
- 🔴 error tracker reports lastError
Severity ordering: error > offline > pending > saved. The
worst applicable signal always wins, so a green "Saved" can
never overrule a red "Sync failed".
- Polls `/api/storage/status` every 5s. Cheap GET; status fits
in a few hundred bytes. We pick polling over SSE because the
data is small, the interval is generous, and adding another
long-lived connection is more failure modes than it's worth.
- Tooltip on the error state shows the exact backend message
plus an actionable hint for the most common cause (`statusCode
=== 403` => "your OAuth grant may be missing manage-repos,
sign out and back in").
- `beforeunload` guard pops the browser's "Leave site?" prompt
when state is pending OR error OR offline. The user can no
longer close the tab without being warned that their data
isn't safely synced yet.
- The error badge gets a subtle pulse (background fade between
12% and 22% red) to draw the eye without being obnoxious.
Pending and offline stay flat to avoid attention-seeking noise
during normal use.

Docs
----
- SPECIFICATION.md gains §4.3.1 (Storage Status & Recovery)
describing the tracker, the routes, the SyncIndicator
behaviour, and the recovery escape hatch.
- TESTS.md gains rows 2.4.1 - 2.4.6 covering the error
surface, auth gates and admin export contract.

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/src/create-app.ts

@@ -16,6 +16,7 @@ import { createChatRouter } from "./routes/chat.js";
 import { createPublishRouter } from "./routes/publish.js";
 import { createUploadRouter } from "./routes/upload.js";
 import { createDatasetProxyRouter } from "./routes/dataset-proxy.js";
+import { createStorageRouter } from "./routes/storage.js";
 
 export { debouncedSave, resetSaveTimers, resetPublishedRestored } from "./persistence.js";
 
@@ -409,6 +410,7 @@ export function createApp() {
   app.use("/api/citations", citationsRouter);
   app.use(createPublishRouter({ oauthEnabled, hocuspocus }));
   app.use(createUploadRouter());
+  app.use(createStorageRouter({ oauthEnabled }));
   // Reverse proxy for private-dataset assets. Mounted before any
   // static serving so `/d/*` always wins, never falls through to a
   // 404 from express.static.

backend/src/hf-storage.ts

@@ -42,6 +42,122 @@ export function isHfStorageEnabled(): boolean {
   return Boolean(HF_DATASET_ID && (_cachedToken || ENV_TOKEN));
 }
 
+// ============================================================
+// Storage status tracker
+// ============================================================
+//
+// Every silent failure point in the persistence pipeline used to
+// disappear into `console.error` and the editor would happily
+// keep showing "Saved". This tracker is the single source of
+// truth for "what's the actual state of my data right now":
+// every write/error path updates it, and the /api/storage/status
+// endpoint surfaces it to the frontend SyncIndicator so the user
+// sees the truth, not a comforting lie.
+//
+// Stages we care about:
+//   - `dataset-create` : ensureDatasetExists couldn't create the
+//      backing repo (most common: missing manage-repos scope)
+//   - `local-save`     : writeFileSync into data/<name>.yjs failed
+//      (disk full, readonly FS, permission denied)
+//   - `cloud-push`     : uploadFile into the dataset failed (HF
+//      down, token expired, network blip)
+//
+// We deliberately keep this in-memory: it's per-container,
+// non-critical, and the frontend polls every few seconds anyway.
+
+export type StorageErrorStage = "dataset-create" | "local-save" | "cloud-push";
+
+export interface StorageError {
+  stage: StorageErrorStage;
+  message: string;
+  statusCode?: number;
+  at: number;
+  /** Doc name when the failure is per-doc (local-save, cloud-push). */
+  docName?: string;
+}
+
+export interface StorageStatus {
+  enabled: boolean;
+  datasetId: string;
+  datasetReady: boolean;
+  /** ms epoch of the last successful local writeFileSync. */
+  lastLocalSaveAt: number | null;
+  /** ms epoch of the last successful HF dataset push. */
+  lastCloudPushAt: number | null;
+  /** True while a debounced push timer is armed. */
+  pendingPush: boolean;
+  /** Last error in the pipeline, or null if everything's fine. */
+  lastError: StorageError | null;
+}
+
+const status: StorageStatus = {
+  enabled: false,
+  datasetId: HF_DATASET_ID,
+  datasetReady: false,
+  lastLocalSaveAt: null,
+  lastCloudPushAt: null,
+  pendingPush: false,
+  lastError: null,
+};
+
+export function getStorageStatus(): StorageStatus {
+  // Refresh `enabled` on every read - it depends on whether we've
+  // received a user token yet, which can flip mid-session.
+  return { ...status, enabled: isHfStorageEnabled() };
+}
+
+export function recordLocalSave(docName: string): void {
+  status.lastLocalSaveAt = Date.now();
+  // Local save success clears a prior local-save error for the
+  // same doc, but leaves cloud-push / dataset-create errors alone
+  // since those are independent.
+  if (status.lastError?.stage === "local-save" && status.lastError.docName === docName) {
+    status.lastError = null;
+  }
+}
+
+export function recordLocalSaveError(docName: string, err: unknown): void {
+  status.lastError = {
+    stage: "local-save",
+    message: (err as Error)?.message || String(err),
+    at: Date.now(),
+    docName,
+  };
+}
+
+function recordCloudPush(docName: string): void {
+  status.lastCloudPushAt = Date.now();
+  if (status.lastError?.stage === "cloud-push" && status.lastError.docName === docName) {
+    status.lastError = null;
+  }
+}
+
+function recordCloudPushError(docName: string, err: unknown, statusCode?: number): void {
+  status.lastError = {
+    stage: "cloud-push",
+    message: (err as Error)?.message || String(err),
+    statusCode,
+    at: Date.now(),
+    docName,
+  };
+}
+
+function recordDatasetReady(): void {
+  status.datasetReady = true;
+  if (status.lastError?.stage === "dataset-create") {
+    status.lastError = null;
+  }
+}
+
+function recordDatasetError(err: unknown, statusCode?: number): void {
+  status.lastError = {
+    stage: "dataset-create",
+    message: (err as Error)?.message || String(err),
+    statusCode,
+    at: Date.now(),
+  };
+}
+
 /**
  * Public-facing base URL the editor is reachable at, used to build
  * absolute proxy URLs for assets that need to render outside the
@@ -97,10 +213,12 @@ export async function ensureDatasetExists(token?: string): Promise<void> {
         `[hf-storage] failed to create dataset ${HF_DATASET_ID}` +
           ` (status=${statusCode ?? "unknown"}): ${message}`,
       );
+      recordDatasetError(err, statusCode);
       return;
     }
   }
   _datasetReady = true;
+  recordDatasetReady();
 }
 
 // ---------- Images ----------
@@ -139,12 +257,18 @@ export function schedulePush(docName: string, state: Buffer): void {
 
   const timer = setTimeout(() => pushDocument(docName), DEBOUNCE_MS);
   dirtyDocs.set(docName, { state, timer });
+  status.pendingPush = true;
 }
 
 async function pushDocument(docName: string): Promise<void> {
   const entry = dirtyDocs.get(docName);
   if (!entry) return;
   dirtyDocs.delete(docName);
+  // Update `pendingPush` based on whether OTHER docs still have a
+  // timer armed. A single editor only ever touches one doc, so in
+  // practice this is always false after `delete`, but the multi-doc
+  // case must not lie either.
+  status.pendingPush = dirtyDocs.size > 0;
 
   await ensureDatasetExists();
 
@@ -159,8 +283,14 @@ async function pushDocument(docName: string): Promise<void> {
       commitTitle: `save ${safeName}`,
     });
     console.log(`[hf-storage] pushed ${path}`);
-  } catch (err) {
-    console.error(`[hf-storage] failed to push ${path}:`, err);
+    recordCloudPush(docName);
+  } catch (err: any) {
+    const statusCode = err?.statusCode ?? err?.status;
+    console.error(
+      `[hf-storage] failed to push ${path}` +
+        ` (status=${statusCode ?? "unknown"}): ${(err as Error)?.message || err}`,
+    );
+    recordCloudPushError(docName, err, statusCode);
   }
 }
 

backend/src/persistence.ts

@@ -8,6 +8,8 @@ import {
   setUserToken,
   pullPublishedAssets,
   schedulePush,
+  recordLocalSave,
+  recordLocalSaveError,
 } from "./hf-storage.js";
 
 const DEFAULT_DOC_NAME = "default";
@@ -27,12 +29,19 @@ export function debouncedSave(documentName: string, ydoc: Y.Doc) {
       const buf = Buffer.from(state);
       writeFileSync(docPath(documentName), buf);
       lastSaveTimestamp.set(documentName, Date.now());
+      recordLocalSave(documentName);
       console.log(`[persist] saved "${documentName}": ${buf.length} bytes`);
 
       if (isHfStorageEnabled()) {
         schedulePush(documentName, buf);
       }
     } catch (err) {
+      // A failed local save is the most dangerous silent failure
+      // because the WS layer already ack'd the edit to the client,
+      // who therefore sees "Saved" while nothing is on disk. Push
+      // the error into the status tracker so the SyncIndicator can
+      // flip to "Local save failed" within a few seconds.
+      recordLocalSaveError(documentName, err);
       console.error(`[persist] failed to save "${documentName}":`, (err as Error).message);
     }
   }, SAVE_DEBOUNCE_MS));

backend/src/routes/auth.ts

@@ -7,7 +7,7 @@ import {
   handleOAuthCallback,
   handleOAuthLogout,
 } from "../auth.js";
-import { setUserToken } from "../hf-storage.js";
+import { setUserToken, ensureDatasetExists } from "../hf-storage.js";
 import { ensurePublishedRestored } from "../persistence.js";
 
 export interface AuthContext {
@@ -61,6 +61,19 @@ export function createAuthRouter(ctx: AuthContext): Router {
     if (user.canEdit && token) {
       setUserToken(token);
       ensurePublishedRestored(token).catch(() => {});
+      // Eagerly try to create the backing dataset on first login
+      // (instead of waiting for the first edit + 12s debounce). If
+      // creation fails - missing manage-repos scope, org policy
+      // blocking the create, etc. - the error lands in the
+      // storage-status tracker right away, and the editor's
+      // SyncIndicator can flash a red "Cloud storage error" on the
+      // first poll. Without this, a misconfigured fork looks
+      // perfectly healthy until the user has typed something and
+      // waited half a minute, by which point they've already
+      // assumed everything is fine.
+      ensureDatasetExists(token).catch((err) => {
+        console.warn("[auth] eager ensureDatasetExists failed:", (err as Error).message);
+      });
     }
 
     res.json({

backend/src/routes/storage.ts

@@ -0,0 +1,87 @@
+import { Router, type Request, type Response } from "express";
+import { createReadStream, existsSync } from "fs";
+import { extractToken, resolveUser } from "../auth.js";
+import { getStorageStatus } from "../hf-storage.js";
+import { docPath, sanitizeName } from "../utils.js";
+
+interface StorageContext {
+  oauthEnabled: boolean;
+}
+
+/**
+ * Routes that surface the state of the persistence pipeline and
+ * provide manual escape hatches for disaster recovery.
+ *
+ *   GET /api/storage/status
+ *     Returns the current pipeline state (datasetReady,
+ *     lastLocalSaveAt, lastCloudPushAt, pendingPush, lastError).
+ *     Polled by the SyncIndicator every few seconds. Auth-gated to
+ *     canEdit so we don't leak error details (which may include
+ *     dataset ids) to anonymous viewers.
+ *
+ *   GET /api/admin/export-doc?name=<docName>
+ *     Streams the raw `.yjs` file off disk so an editor can
+ *     download a snapshot manually. The cardinal use case is
+ *     "the cloud push has been failing for hours, the container
+ *     is about to rebuild, I need to get my data out NOW". Same
+ *     canEdit gate.
+ */
+export function createStorageRouter(ctx: StorageContext): Router {
+  const router = Router();
+
+  router.get("/api/storage/status", async (req, res) => {
+    if (ctx.oauthEnabled) {
+      const token = extractToken(req.headers.cookie);
+      const user = await resolveUser(token);
+      if (!user || !user.canEdit) {
+        res.status(403).json({ error: "Unauthorized" });
+        return;
+      }
+    }
+    res.json(getStorageStatus());
+  });
+
+  router.get("/api/admin/export-doc", async (req: Request, res: Response) => {
+    if (ctx.oauthEnabled) {
+      const token = extractToken(req.headers.cookie);
+      const user = await resolveUser(token);
+      if (!user || !user.canEdit) {
+        res.status(403).json({ error: "Unauthorized" });
+        return;
+      }
+    }
+
+    // `name` is the doc id; default to the only doc the editor
+    // currently supports ("default"). Sanitised before touching FS.
+    const rawName = typeof req.query.name === "string" ? req.query.name : "default";
+    const safeName = sanitizeName(rawName);
+    const path = docPath(rawName);
+
+    if (!existsSync(path)) {
+      res.status(404).json({ error: "No on-disk snapshot for that doc" });
+      return;
+    }
+
+    // Force a download with a date-stamped filename so multiple
+    // exports don't overwrite each other in the user's downloads
+    // folder. ISO date without colons (Windows / macOS Downloads
+    // are happier without them).
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    res.setHeader("Content-Type", "application/octet-stream");
+    res.setHeader(
+      "Content-Disposition",
+      `attachment; filename="${safeName}-${stamp}.yjs"`,
+    );
+    res.setHeader("Cache-Control", "no-store");
+
+    const stream = createReadStream(path);
+    stream.on("error", (err) => {
+      console.error(`[admin-export] stream error for ${safeName}:`, err.message);
+      if (!res.headersSent) res.status(500).end();
+      else res.end();
+    });
+    stream.pipe(res);
+  });
+
+  return router;
+}

docs/SPECIFICATION.md

@@ -99,7 +99,17 @@ All types are concurrently editable by multiple users and persist to `data/defau
 - **Images**: `images/<uuid-filename>` referenced from articles via `/d/images/...` proxy URLs
 - `flushAll()` on `SIGTERM`/`SIGINT` to push pending changes
 
-### 4.3.1 Dataset Reverse Proxy (`/d/*`)
+### 4.3.1 Storage Status & Recovery
+
+The persistence pipeline used to fail silently in multiple places (`createRepo` 403 on a missing scope, `uploadFile` 5xx mid-debounce, `writeFileSync` on a readonly FS, ...) and the editor would happily keep showing "Saved". To make data first-class:
+
+- **In-memory tracker** in `hf-storage.ts` records `datasetReady`, `lastLocalSaveAt`, `lastCloudPushAt`, `pendingPush`, `lastError {stage, message, statusCode, at, docName}`. Every write path updates it; every error path records the failure.
+- **`GET /api/storage/status`** exposes the tracker (canEdit-gated). The frontend `SyncIndicator` polls it every 5s and displays a three-state badge: green "Saved" / amber "Saving..." / **red "Storage error"** (pulsing, with the exact reason in the tooltip + actionable hint for the 403 / missing-scope case).
+- **Eager `ensureDatasetExists`** on first `/api/auth/status` for a canEdit user. A misconfigured fork now surfaces its error within ~10s of login instead of waiting for an edit + 12s debounce cycle.
+- **`beforeunload` guard** on the editor: if a local edit is in flight, a push is armed, the WS is offline, or the tracker reports an error, the browser pops the standard "Leave site?" confirm.
+- **`GET /api/admin/export-doc`** (canEdit-gated) streams the on-disk `.yjs` snapshot as a download. The escape hatch for disaster recovery: when the cloud push has been failing and the container is about to rebuild, an admin can grab the doc bytes manually.
+
+### 4.3.2 Dataset Reverse Proxy (`/d/*`)
 
 Since the dataset is private, anonymous viewers of a published article can't fetch its images / PDF / og:image directly from `huggingface.co/datasets/...`. The editor server exposes `GET /d/:path*` as an authenticated forward-proxy:
 

docs/TESTS.md

@@ -90,6 +90,17 @@ Data loss is game over for a collaborative editor.
 | 2.3.3 | Proxy serves images | Given an uploaded image / When GET `/d/images/<file>` / Then 200 + image bytes (proxy attaches a server-side token to fetch the private HF dataset) | P1 |
 | 2.3.4 | Proxy whitelist | Given any path under `/d/articles/...` (raw Y.js drafts) / When GET / Then 404 - never expose drafts via the proxy | P0 |
 
+### 2.4 Storage status & disaster recovery
+
+| # | Test | Given / When / Then | Priority |
+|---|------|---------------------|----------|
+| 2.4.1 | Status surfaces dataset error | Given `createRepo` returns 403 / When GET /api/storage/status / Then response `lastError.stage === "dataset-create"` with `statusCode: 403` | P0 |
+| 2.4.2 | Status clears on recovery | Given a previous push error / When the next push succeeds / Then `lastError` is null and `lastCloudPushAt` is updated | P1 |
+| 2.4.3 | Status auth-gated | Given an anonymous request (oauthEnabled) / When GET /api/storage/status / Then 403 - don't leak dataset error details | P1 |
+| 2.4.4 | Eager creation on login | Given a successful /api/auth/status with canEdit / When the request completes / Then `ensureDatasetExists` has been attempted (success surfaces within one storage-status poll, failure surfaces too) | P0 |
+| 2.4.5 | Admin export streams .yjs | Given an editor user / When GET /api/admin/export-doc?name=default / Then 200 + `Content-Disposition: attachment` + raw .yjs body | P1 |
+| 2.4.6 | Admin export auth-gated | Given a non-canEdit request / When GET /api/admin/export-doc / Then 403 | P0 |
+
 ---
 
 ## 3. API Routes - HTTP Contracts (P1)

frontend/src/components/SyncIndicator.tsx

@@ -1,94 +1,97 @@
 import { useEffect, useRef, useState } from "react";
 import type { Editor as TiptapEditor } from "@tiptap/core";
 import type { HocuspocusProvider } from "@hocuspocus/provider";
-import { Cloud, CloudOff, Loader2 } from "lucide-react";
+import { Cloud, CloudOff, AlertTriangle, Loader2 } from "lucide-react";
 import { Tooltip } from "./Tooltip";
 
-type SyncStatus = "connected" | "syncing" | "saved" | "disconnected";
+/**
+ * Server-side persistence pipeline state, as returned by
+ * `GET /api/storage/status`. Mirrors the shape of `StorageStatus`
+ * in `backend/src/hf-storage.ts` - if you add a field there, add
+ * it here too.
+ */
+interface StorageStatus {
+  enabled: boolean;
+  datasetId: string;
+  datasetReady: boolean;
+  lastLocalSaveAt: number | null;
+  lastCloudPushAt: number | null;
+  pendingPush: boolean;
+  lastError: {
+    stage: "dataset-create" | "local-save" | "cloud-push";
+    message: string;
+    statusCode?: number;
+    at: number;
+    docName?: string;
+  } | null;
+}
+
+/**
+ * What the user sees in the top bar, derived from BOTH the WS
+ * connection state AND the server-side persistence pipeline.
+ *
+ * Severity ordering (worst first): error > offline > pending > saved.
+ * The displayed status is always the worst applicable signal, so
+ * a green "Saved" never wins over a red "Sync failed".
+ */
+type DisplayStatus =
+  | "saved"        // WS connected + dataset ready + no error + recent push
+  | "pending"      // edit in flight or push timer armed
+  | "offline"      // WS disconnected (network or container restart)
+  | "error";       // backend reports lastError in the pipeline
 
 interface Props {
   editorInstance: TiptapEditor | null;
   providerRef: { current: HocuspocusProvider | null };
 }
 
-/**
- * Tiny connection/saving indicator for the editor top bar. Listens to the
- * Hocuspocus provider (`connect` / `disconnect` / `synced`) for connection
- * status, and to the underlying Yjs document (`update`) for change
- * activity.
- *
- * Why ydoc.on('update') and not editor.on('update'):
- *   TipTap's `update` event only fires for changes to the prosemirror
- *   document (the article body). The hero (title/subtitle/authors/...)
- *   and the article settings live in sibling Y.Maps on the same ydoc,
- *   and edits there go straight to Yjs without round-tripping through
- *   TipTap. Listening on the prosemirror editor would therefore miss
- *   every hero / settings / citation / embed change and make the user
- *   believe nothing is being saved - even though the backend's
- *   Hocuspocus `onChange` handler is happily persisting the full ydoc
- *   on every Yjs update. Subscribing at the Yjs layer fixes that: we
- *   see every change the backend sees, in the same order it sees them.
- */
+const POLL_MS = 5_000;
+
 export function SyncIndicator({ editorInstance: _editorInstance, providerRef }: Props) {
-  const [status, setStatus] = useState<SyncStatus>("disconnected");
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // The provider is created lazily by <Editor> and assigned to
-  // providerRef AFTER this component mounts. A ref doesn't trigger
-  // re-renders, so a useEffect with [providerRef] only fires once -
-  // typically before the provider exists - and would never re-run to
-  // attach listeners. We poll providerRef.current here until it
-  // populates, then subscribe and stop polling. Once we hold the
-  // provider reference, we also seed the initial status from the
-  // underlying ws layer so we don't get stuck on "disconnected" if
-  // we missed the very first `connect` event.
+  const [wsConnected, setWsConnected] = useState(false);
+  const [hasLocalEdit, setHasLocalEdit] = useState(false);
+  const [serverStatus, setServerStatus] = useState<StorageStatus | null>(null);
+  const editTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // ---- WS layer: connection + edit activity ------------------------------
+  // Same lazy-provider polling pattern as the previous version: the
+  // provider is created by <Editor> AFTER this component mounts, so a
+  // useEffect([providerRef]) alone would never re-fire when it lands.
   useEffect(() => {
-    let provider: HocuspocusProvider | null = providerRef.current;
     let pollId: ReturnType<typeof setInterval> | null = null;
 
     const attach = (p: HocuspocusProvider) => {
-      const onConnect = () => setStatus("saved");
-      const onDisconnect = () => setStatus("disconnected");
-      const onSynced = () => setStatus("saved");
+      const onConnect = () => setWsConnected(true);
+      const onDisconnect = () => setWsConnected(false);
+      const onSynced = () => setWsConnected(true);
       p.on("connect", onConnect);
       p.on("disconnect", onDisconnect);
       p.on("synced", onSynced);
 
-      const seedStatus = () => {
-        const wsProvider = (p as any).configuration?.websocketProvider;
-        const s = wsProvider?.status;
-        if (s === "connected") setStatus("saved");
-        else if (s === "connecting") setStatus("disconnected");
-        else setStatus("disconnected");
+      // Seed + 1s reconcile loop (some HF proxies eat the first
+      // `connect` event; without this we'd stay "Offline" forever).
+      const seed = () => {
+        const ws = (p as any).configuration?.websocketProvider;
+        setWsConnected(ws?.status === "connected");
       };
-      seedStatus();
-      // Connection may still be in flight when we first attach; the
-      // `connect` event fires once it lands. As a safety net (some
-      // browsers / HF proxy flows have been observed to skip the
-      // first event), poll the underlying ws status every second
-      // and reconcile. Cheap and self-correcting.
-      const reconcileId = setInterval(seedStatus, 1000);
-
-      // Listen at the Yjs layer for change activity. Hocuspocus
-      // stores the ydoc on `provider.document` (it's the same Y.Doc
-      // we passed in when constructing the provider). Filtering out
-      // updates whose origin is the provider itself avoids flashing
-      // "Saving..." every time we just RECEIVED collab updates from
-      // someone else - those don't need to be saved by us, they were
-      // saved by their author.
+      seed();
+      const reconcile = setInterval(seed, 1000);
+
+      // Listen at the Yjs layer so we see EVERY change (TipTap's
+      // own `update` event misses hero/settings/citation edits
+      // because those bypass prosemirror).
       const ydoc = (p as any).document as
         | { on: Function; off: Function }
         | undefined;
-      const onYUpdate = (_update: Uint8Array, origin: unknown) => {
-        if (origin === p) return;
-        setStatus("syncing");
-        if (timerRef.current) clearTimeout(timerRef.current);
-        timerRef.current = setTimeout(() => {
-          const wsProvider = (p as any).configuration?.websocketProvider;
-          setStatus(
-            wsProvider?.status === "connected" ? "saved" : "disconnected",
-          );
-        }, 1500);
+      const onYUpdate = (_u: Uint8Array, origin: unknown) => {
+        if (origin === p) return; // remote update, not ours
+        setHasLocalEdit(true);
+        if (editTimerRef.current) clearTimeout(editTimerRef.current);
+        // Local edit "settles" 1.5s after the last keystroke; this
+        // is also roughly when the backend's `debouncedSave` fires
+        // (2s), so the indicator briefly flashes pending then
+        // recovers to saved/error based on the next poll.
+        editTimerRef.current = setTimeout(() => setHasLocalEdit(false), 1500);
       };
       ydoc?.on?.("update", onYUpdate);
 
@@ -97,26 +100,24 @@ export function SyncIndicator({ editorInstance: _editorInstance, providerRef }:
         p.off("disconnect", onDisconnect);
         p.off("synced", onSynced);
         ydoc?.off?.("update", onYUpdate);
-        clearInterval(reconcileId);
+        clearInterval(reconcile);
       };
     };
 
-    if (provider) {
-      return attach(provider);
-    }
-
-    // Provider not ready yet - wait for it.
     let cleanup: (() => void) | null = null;
-    pollId = setInterval(() => {
-      const p = providerRef.current;
-      if (!p) return;
-      if (pollId) {
-        clearInterval(pollId);
-        pollId = null;
-      }
-      provider = p;
-      cleanup = attach(p);
-    }, 100);
+    if (providerRef.current) {
+      cleanup = attach(providerRef.current);
+    } else {
+      pollId = setInterval(() => {
+        const p = providerRef.current;
+        if (!p) return;
+        if (pollId) {
+          clearInterval(pollId);
+          pollId = null;
+        }
+        cleanup = attach(p);
+      }, 100);
+    }
 
     return () => {
       if (pollId) clearInterval(pollId);
@@ -124,27 +125,150 @@ export function SyncIndicator({ editorInstance: _editorInstance, providerRef }:
     };
   }, [providerRef]);
 
-  const label =
-    status === "saved" ? "Saved" :
-    status === "syncing" ? "Saving..." :
-    status === "connected" ? "Connected" :
-    "Offline";
+  // ---- Server pipeline polling -------------------------------------------
+  // Cheap GET every 5s. The backend tracker updates in-process on
+  // every save/push/error so the worst-case latency for surfacing
+  // a problem is one poll interval. We don't use SSE/WS for this
+  // because the data is tiny, the polling interval is generous,
+  // and adding another long-lived connection is more failure modes
+  // than it's worth.
+  useEffect(() => {
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
 
-  const tooltip =
-    status === "saved" ? "All changes saved" :
-    status === "syncing" ? "Saving..." :
-    status === "connected" ? "Connected" :
-    "Disconnected";
+    const poll = async () => {
+      try {
+        const res = await fetch("/api/storage/status", {
+          credentials: "include",
+        });
+        if (cancelled) return;
+        if (res.ok) {
+          const data = (await res.json()) as StorageStatus;
+          setServerStatus(data);
+        } else if (res.status === 403) {
+          // Viewer (not an editor) - storage status isn't relevant
+          // to them. Stop polling.
+          return;
+        }
+      } catch {
+        // Network blip - keep trying. The WS disconnection will
+        // dominate the UI anyway in that case.
+      }
+      if (!cancelled) {
+        timer = setTimeout(poll, POLL_MS);
+      }
+    };
+    poll();
+
+    return () => {
+      cancelled = true;
+      if (timer) clearTimeout(timer);
+    };
+  }, []);
+
+  // ---- Derive the displayed status ---------------------------------------
+  // Worst-applicable wins (see DisplayStatus jsdoc).
+  const status: DisplayStatus = (() => {
+    if (serverStatus?.lastError) return "error";
+    if (!wsConnected) return "offline";
+    if (hasLocalEdit || serverStatus?.pendingPush) return "pending";
+    return "saved";
+  })();
+
+  // ---- beforeunload guard ------------------------------------------------
+  // If there's an unsynced local edit OR a pending push OR a known
+  // sync error, browsers should pop the standard "Leave site?"
+  // confirmation. The exact message is ignored by modern browsers
+  // (Chrome/Safari/Firefox show their own generic copy) but
+  // setting `returnValue` is what triggers the prompt.
+  useEffect(() => {
+    const needsGuard = status === "pending" || status === "error" || status === "offline";
+    if (!needsGuard) return;
+
+    const handler = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      // Legacy browsers (and TS types still hold this) want a string.
+      e.returnValue = "";
+      return "";
+    };
+    window.addEventListener("beforeunload", handler);
+    return () => window.removeEventListener("beforeunload", handler);
+  }, [status]);
+
+  // ---- Render ------------------------------------------------------------
+  const { icon, label, tooltip } = renderState(status, serverStatus);
 
   return (
     <Tooltip title={tooltip}>
-      <span className={`sync-indicator sync-indicator--${status}`}>
-        {status === "syncing" && <Loader2 size={14} className="spin" />}
-        {status === "saved" && <Cloud size={14} />}
-        {status === "connected" && <Cloud size={14} />}
-        {status === "disconnected" && <CloudOff size={14} />}
+      <span
+        className={`sync-indicator sync-indicator--${status}`}
+        role="status"
+        aria-live="polite"
+      >
+        {icon}
         <span className="sync-indicator__label">{label}</span>
       </span>
     </Tooltip>
   );
 }
+
+function renderState(status: DisplayStatus, server: StorageStatus | null) {
+  switch (status) {
+    case "error": {
+      const err = server?.lastError;
+      const stageLabel: Record<string, string> = {
+        "dataset-create": "Cloud storage setup failed",
+        "local-save": "Local save failed",
+        "cloud-push": "Cloud sync failed",
+      };
+      const label = err ? stageLabel[err.stage] ?? "Storage error" : "Storage error";
+      const hint = err?.statusCode === 403
+        ? " - your OAuth grant may be missing the `manage-repos` scope. Sign out and back in."
+        : "";
+      const tooltip = err
+        ? `${label}: ${err.message}${hint}`
+        : "Storage error";
+      return {
+        icon: <AlertTriangle size={14} />,
+        label,
+        tooltip,
+      };
+    }
+    case "offline":
+      return {
+        icon: <CloudOff size={14} />,
+        label: "Offline",
+        tooltip: "Disconnected - reconnecting...",
+      };
+    case "pending":
+      return {
+        icon: <Loader2 size={14} className="spin" />,
+        label: "Saving...",
+        tooltip: server?.datasetReady === false
+          ? "Saving locally - cloud sync starts after first successful dataset creation"
+          : "Saving to cloud...",
+      };
+    case "saved":
+    default: {
+      const last = server?.lastCloudPushAt;
+      const tooltip = last
+        ? `All changes saved · last cloud sync ${formatRelative(last)}`
+        : server?.datasetReady
+        ? "All changes saved"
+        : "Saved locally - cloud sync will start on first change";
+      return {
+        icon: <Cloud size={14} />,
+        label: "Saved",
+        tooltip,
+      };
+    }
+  }
+}
+
+function formatRelative(ts: number): string {
+  const diff = Date.now() - ts;
+  if (diff < 5_000) return "just now";
+  if (diff < 60_000) return `${Math.round(diff / 1000)}s ago`;
+  if (diff < 3_600_000) return `${Math.round(diff / 60_000)}min ago`;
+  return new Date(ts).toLocaleTimeString();
+}

frontend/src/styles/_ui.css

@@ -1359,9 +1359,21 @@ dialog.ed-dialog.ed-dialog--author { max-width: 480px; }
 }
 .sync-indicator__label { white-space: nowrap; }
 .sync-indicator--saved { color: var(--ed-text-disabled); opacity: 0.7; }
-.sync-indicator--syncing { color: var(--ed-accent, #958df1); opacity: 1; }
-.sync-indicator--connected { color: var(--ed-text-disabled); opacity: 0.5; }
-.sync-indicator--disconnected { color: #e15759; opacity: 1; }
+.sync-indicator--pending { color: var(--ed-accent, #958df1); opacity: 1; }
+.sync-indicator--offline { color: #e15759; opacity: 1; }
+/* `error` is the loudest state - bright red, slight bg tint, and
+ * a pulsing dot to scream "your data isn't safe". The other
+ * states stay flat to avoid attention-seeking noise. */
+.sync-indicator--error {
+  color: #e15759;
+  background: color-mix(in srgb, #e15759 12%, transparent);
+  opacity: 1;
+  animation: sync-indicator-pulse 2s ease-in-out infinite;
+}
+@keyframes sync-indicator-pulse {
+  0%, 100% { background: color-mix(in srgb, #e15759 12%, transparent); }
+  50%      { background: color-mix(in srgb, #e15759 22%, transparent); }
+}
 .sync-indicator .spin {
   animation: sync-spin 1s linear infinite;
 }