fix(sync): reconcile local cache on startup

Author: tnunamak

packages/core/src/sync/engine/sync-manager.ts

@@ -67,6 +67,7 @@ export function createSyncManager(
   let errors: SyncError[] = [];
   let cycleInFlight: Promise<void> | null = null;
   let rerunRequested = false;
+  let needsFullReconcile = true;
 
   async function runCycle(): Promise<void> {
     // Prevent concurrent cycles
@@ -119,9 +120,13 @@ export function createSyncManager(
 
         try {
           // Download new remote files
-          const downloadResults = await downloadAll(downloadDeps);
+          const fullReconcile = needsFullReconcile;
+          const downloadResults = await downloadAll(downloadDeps, {
+            fullReconcile,
+          });
+          needsFullReconcile = false;
           downloadDeps.logger.debug(
-            { downloaded: downloadResults.length },
+            { downloaded: downloadResults.length, fullReconcile },
             "Download cycle complete",
           );
         } catch (err) {

packages/core/src/sync/workers/download.test.ts

@@ -731,6 +731,34 @@ describe("download worker", () => {
       );
     });
 
+    it("can reconcile missing local records even when the cursor is already advanced", async () => {
+      const deps = makeMockDeps();
+      (deps.cursor.read as ReturnType<typeof vi.fn>).mockResolvedValue(
+        "2026-06-01T00:00:00Z",
+      );
+      (
+        deps.gateway.listFilesSince as ReturnType<typeof vi.fn>
+      ).mockResolvedValue({
+        files: [makeFileRecord({ createdAt: "2026-01-21T10:00:00Z" })],
+        cursor: "2026-06-10T00:00:00Z",
+      });
+
+      const results = await downloadAll(deps, { fullReconcile: true });
+
+      expect(results).toHaveLength(1);
+      expect(deps.cursor.read).not.toHaveBeenCalled();
+      expect(deps.gateway.listFilesSince).toHaveBeenCalledWith(OWNER, null, {
+        includeDeleted: true,
+      });
+      expect(deps.storageAdapter.download).toHaveBeenCalledWith(STORAGE_URL);
+      expect(deps.storage.insertEntry).toHaveBeenCalledWith(
+        expect.objectContaining({
+          fileId: FILE_ID,
+          scope: SCOPE,
+        }),
+      );
+    });
+
     it("reconciles a remote deletion by dropping the local copy (no download)", async () => {
       const deps = makeMockDeps();
       const deletedRecord = makeFileRecord({

packages/core/src/sync/workers/download.ts

@@ -53,6 +53,15 @@ export interface DownloadResult {
   path: string;
 }
 
+export interface DownloadAllOptions {
+  /**
+   * Ignore the stored incremental cursor and reconcile from the beginning of the
+   * owner's file registry. This repairs browser caches whose cursor advanced
+   * while local IndexedDB/OPFS lost or failed to index some older records.
+   */
+  fullReconcile?: boolean;
+}
+
 interface SyncFailureMetadata {
   stage?: SyncFailureStage;
   scope?: string;
@@ -284,6 +293,7 @@ export async function downloadOne(
  */
 export async function downloadAll(
   deps: DownloadWorkerDeps,
+  options: DownloadAllOptions = {},
 ): Promise<DownloadResult[]> {
   const { gateway, cursor, serverOwner, logger } = deps;
   const syncRunId = createSyncRunId();
@@ -292,7 +302,14 @@ export async function downloadAll(
 
   // 1. Read cursor
   const lastProcessedTimestamp =
-    repairSummary.missingEnvelopeEntries > 0 ? null : await cursor.read();
+    options.fullReconcile || repairSummary.missingEnvelopeEntries > 0
+      ? null
+      : await cursor.read();
+  if (options.fullReconcile) {
+    logger.info(
+      "Running full registry reconciliation to repair any missing local scope records",
+    );
+  }
   if (repairSummary.missingEnvelopeEntries > 0) {
     logger.warn(
       { missingEnvelopeEntries: repairSummary.missingEnvelopeEntries },