fix(mega): stop ghost nodes from failing every sync with ENOENT

A node deleted server-side becomes a permanent "ghost" in megajs's
storage.files: the sc delete handler only unlinks parent.children, and
reload() is purely additive (_importFile skips known handles). Since the
provider enumerates from storage.files, a ghost volume-data.json made
every sync fail: the download discarded the readable copy (Promise.all),
and the pre-upload replace delete hit server ENOENT (-9) with a
cache-refresh retry that could never evict the ghost.

- reinitialize(): rebuild storage.files from an empty map so the reload
  mirrors the server exactly (evicts ghosts); restore the old tree on
  transient reload failure. Also strip the stacked api 'sc' listeners
  megajs re-attaches on every reload — double-processed delete packets
  splice(-1) and corrupt sibling arrays in long sessions.
- uploadFile(): replace-all semantics (delete every same-name copy, not
  just the first) and treat a server "already gone" delete answer as
  converged instead of failing the upload.
- downloadVolumeDataFile(): Promise.allSettled — merge the readable
  duplicates, skip not-found ghosts, keep the first readable copy, and
  tolerate NOT_FOUND when deleting the extras. Transient errors still
  propagate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Gnathonic

src/lib/util/sync/providers/mega/mega-provider.test.ts

@@ -382,3 +382,116 @@ describe('MegaProvider.removeDirectoryIfEmpty()', () => {
     expect(storage.api.request).not.toHaveBeenCalled();
   });
 });
+
+describe('MegaProvider ghost-node handling', () => {
+  // A "ghost" is a node deleted server-side that megajs never evicts from
+  // storage.files: its sc delete handler only unlinks parent.children, and
+  // reload() is purely additive (_importFile skips known handles). Ghosts
+  // made every sync fail: the pre-upload replace delete hit server ENOENT (-9)
+  // and the reload-based retry could never remove the ghost.
+
+  function makeMokuroFolder() {
+    return {
+      name: 'mokuro-reader',
+      directory: true,
+      upload: vi.fn((_opts: any, _buf: any, cb: (e: Error | null, f?: any) => void) => {
+        queueMicrotask(() => cb(null, { nodeId: 'fresh-node' }));
+      })
+    } as any;
+  }
+
+  function makeFile(name: string, parent: any, deleteError: Error | null = null) {
+    return {
+      name,
+      directory: false,
+      parent,
+      delete: vi.fn((_force: boolean, cb: (e: Error | null) => void) => {
+        queueMicrotask(() => cb(deleteError));
+      })
+    } as any;
+  }
+
+  async function loginWithTree(files: Record<string, any>) {
+    storageState.files = files;
+    const provider = new MegaProvider();
+    await provider.whenReady();
+    await provider.login({ email: 'a@b.c', password: 'secret' });
+    return provider;
+  }
+
+  it('uploadFile tolerates ENOENT when deleting a ghost copy and still uploads', async () => {
+    const folder = makeMokuroFolder();
+    const ghost = makeFile(
+      'volume-data.json',
+      folder,
+      new Error('ENOENT (-9): Object (typically, node or user) not found. Wrong password?')
+    );
+    const provider = await loginWithTree({ root: folder, ghost });
+
+    const fileId = await provider.uploadFile('volume-data.json', new Uint8Array([1, 2, 3]));
+
+    expect(ghost.delete).toHaveBeenCalled();
+    expect(folder.upload).toHaveBeenCalledOnce();
+    expect(fileId).toBe('fresh-node');
+  });
+
+  it('uploadFile replaces every same-name copy, not just the first', async () => {
+    const folder = makeMokuroFolder();
+    const dupe1 = makeFile('volume-data.json', folder);
+    const dupe2 = makeFile('volume-data.json', folder);
+    const provider = await loginWithTree({ root: folder, dupe1, dupe2 });
+
+    await provider.uploadFile('volume-data.json', new Uint8Array([1]));
+
+    expect(dupe1.delete).toHaveBeenCalledOnce();
+    expect(dupe2.delete).toHaveBeenCalledOnce();
+    expect(folder.upload).toHaveBeenCalledOnce();
+  });
+
+  it('reinitialize rebuilds storage.files so server-deleted ghosts are evicted', async () => {
+    const folder = makeMokuroFolder();
+    const ghost = makeFile('volume-data.json', folder);
+    const real = makeFile('real.cbz', folder);
+    const provider = await loginWithTree({ root: folder, ghost });
+    const storage = (provider as any).storage;
+
+    // Mirror megajs reload() semantics: additive import of the server's
+    // node set (which no longer contains the ghost).
+    storage.reload = vi.fn(async () => {
+      const server: Record<string, any> = { root: folder, real };
+      for (const [handle, node] of Object.entries(server)) {
+        if (!storage.files[handle]) storage.files[handle] = node;
+      }
+    });
+
+    await (provider as any).reinitialize();
+
+    expect(Object.keys(storage.files).sort()).toEqual(['real', 'root']);
+  });
+
+  it('reinitialize strips stale sc listeners before reloading (megajs stacks one per reload)', async () => {
+    const folder = makeMokuroFolder();
+    const provider = await loginWithTree({ root: folder });
+    const storage = (provider as any).storage;
+    storage.api = { removeAllListeners: vi.fn() };
+
+    await (provider as any).reinitialize();
+
+    expect(storage.api.removeAllListeners).toHaveBeenCalledWith('sc');
+  });
+
+  it('reinitialize keeps the previous tree when the reload fails transiently', async () => {
+    const folder = makeMokuroFolder();
+    const ghost = makeFile('volume-data.json', folder);
+    const provider = await loginWithTree({ root: folder, ghost });
+    const storage = (provider as any).storage;
+    storage.reload = vi.fn(async () => {
+      throw new Error('ETEMPUNAVAIL (-18): A temporary congestion or server malfunction');
+    });
+
+    await (provider as any).reinitialize();
+
+    expect(provider.isAuthenticated()).toBe(true);
+    expect(Object.keys(storage.files).sort()).toEqual(['ghost', 'root']);
+  });
+});

src/lib/util/sync/providers/mega/mega-provider.ts

@@ -94,6 +94,12 @@ async function retryWithBackoff<T>(
   throw lastError;
 }
 
+/** megajs surfaces a server-side missing node as `ENOENT (-9)`. */
+function isMegaNotFoundError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes('ENOENT') || message.includes('(-9)');
+}
+
 /**
  * Smart retry wrapper for MEGA operations that may fail due to stale cache
  * When two devices sync back and forth, file IDs change but local cache is stale
@@ -443,9 +449,29 @@ export class MegaProvider implements SyncProvider {
       // server-side. Every storage (login, restore, reinitialize, upload worker)
       // reuses the one persisted sid, so closing any of them invalidates the
       // stored token and makes every later request fail with ESID (-15).
-      await this.storage.reload(true);
+      //
+      // Two megajs reload() quirks force extra work here:
+      // - reload() attaches a NEW api 'sc' handler on every call without
+      //   removing the old one. Stacked handlers process each server packet
+      //   N times, and a re-processed delete splices with indexOf === -1,
+      //   silently removing an unrelated sibling from the tree.
+      // - reload() only ADDS nodes (_importFile skips known handles) and the
+      //   sc delete handler never removes nodes from storage.files, so a node
+      //   deleted server-side survives every reload as a permanent "ghost"
+      //   that fails all later operations with ENOENT (-9). Rebuild from an
+      //   empty map so the reloaded tree exactly mirrors the server.
+      this.storage.api?.removeAllListeners?.('sc');
+      const previousFiles = this.storage.files;
+      this.storage.files = {};
+      try {
+        await this.storage.reload(true);
+      } catch (error) {
+        // Keep the old (stale but usable) tree if the reload didn't complete.
+        this.storage.files = previousFiles;
+        throw error;
+      }
       this.mokuroFolder = null;
-      console.log('✅ MEGA cache reinitialized (in-place reload)');
+      console.log('✅ MEGA cache reinitialized (fresh in-place reload)');
     } catch (error) {
       if (isSessionExpiredError(error)) {
         this.markSessionExpired();
@@ -713,18 +739,21 @@ export class MegaProvider implements SyncProvider {
             buffer = new Uint8Array(arrayBuffer);
           }
 
-          // Check if file already exists
           const children = await this.listFolder(targetFolder);
-          const existingFile = children.find((f: any) => f.name === fileName && !f.directory);
 
-          // Delete existing file if found. Do NOT remove it from
-          // storage.files manually — the sc stream delivers the delete and
-          // megajs applies it; a manual removal makes the later sc packet
-          // crash on a missing node (the original "keepalive crash").
-          if (existingFile) {
+          // Replace semantics: delete EVERY same-name copy (MEGA allows
+          // duplicate names, so racing uploads can leave several). Do NOT
+          // remove them from storage.files manually — the sc stream delivers
+          // the delete and megajs applies it; a manual removal makes the
+          // later sc packet crash on a missing node (the original "keepalive
+          // crash"). A copy can also be a ghost — deleted server-side but
+          // never evicted from storage.files by megajs — so a server
+          // "already gone" answer means converged, not failed.
+          const existingFiles = children.filter((f: any) => f.name === fileName && !f.directory);
+          for (const existingFile of existingFiles) {
             await new Promise<void>((resolve, reject) => {
               existingFile.delete(true, (error: Error | null) => {
-                if (error) reject(error);
+                if (error && !isMegaNotFoundError(error)) reject(error);
                 else resolve();
               });
             });

src/lib/util/sync/unified-sync-service.test.ts

@@ -0,0 +1,168 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ProviderError } from './provider-interface';
+import type { CloudFileMetadata, SyncProvider } from './provider-interface';
+
+const getCache = vi.fn();
+
+vi.mock('./cache-manager', () => ({
+  cacheManager: { getCache: (...args: unknown[]) => getCache(...args) }
+}));
+
+vi.mock('../snackbar', () => ({ showSnackbar: vi.fn() }));
+
+vi.mock('../progress-tracker', () => ({
+  progressTrackerStore: {
+    addProcess: vi.fn(),
+    updateProcess: vi.fn(),
+    removeProcess: vi.fn()
+  }
+}));
+
+vi.mock('$lib/settings', async () => {
+  const { writable } = await import('svelte/store');
+  return {
+    volumesWithTrash: writable({}),
+    profiles: writable({}),
+    profilesWithTrash: writable({}),
+    migrateProfiles: vi.fn((p: unknown) => p),
+    parseVolumesFromJson: vi.fn((json: string) => JSON.parse(json))
+  };
+});
+
+import { unifiedSyncService } from './unified-sync-service';
+
+// downloadVolumeDataFile is private; these tests target it directly because it
+// owns the duplicate-merge behavior that broke MEGA sync (ghost duplicates).
+const svc = unifiedSyncService as any;
+
+function fileMeta(fileId: string): CloudFileMetadata {
+  return {
+    provider: 'mega',
+    fileId,
+    path: 'volume-data.json',
+    modifiedTime: '2026-01-01T00:00:00Z'
+  } as unknown as CloudFileMetadata;
+}
+
+const jsonBlob = (data: unknown) => ({ text: async () => JSON.stringify(data) }) as unknown as Blob;
+
+const notFound = () => new ProviderError('File not found: volume-data.json', 'mega', 'NOT_FOUND');
+
+function makeProvider(
+  download: (file: CloudFileMetadata) => Promise<Blob>,
+  del: (file: CloudFileMetadata) => Promise<void> = async () => {}
+): SyncProvider {
+  return {
+    type: 'mega',
+    downloadFile: vi.fn(download),
+    deleteFile: vi.fn(del)
+  } as unknown as SyncProvider;
+}
+
+function stubCache(files: CloudFileMetadata[]) {
+  const cache = {
+    getAll: vi.fn(() => files),
+    get: vi.fn(() => null),
+    fetch: vi.fn(async () => {})
+  };
+  getCache.mockReturnValue(cache);
+  return cache;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('downloadVolumeDataFile — duplicate handling with ghost copies', () => {
+  const goodData = { 'vol-1': { lastProgressUpdate: '2026-01-02T00:00:00Z', progress: 5 } };
+
+  it('merges the readable copies and skips a ghost duplicate instead of discarding everything', async () => {
+    const [good, ghost] = [fileMeta('good'), fileMeta('ghost')];
+    const cache = stubCache([good, ghost]);
+    const provider = makeProvider(async (file) => {
+      if (file.fileId === 'ghost') throw notFound();
+      return jsonBlob(goodData);
+    });
+
+    const result = await svc.downloadVolumeDataFile(provider);
+
+    expect(result).toEqual(goodData);
+    expect(provider.deleteFile).toHaveBeenCalledTimes(1);
+    expect(provider.deleteFile).toHaveBeenCalledWith(ghost);
+    expect(cache.fetch).not.toHaveBeenCalled();
+  });
+
+  it('keeps the readable copy when the FIRST listed duplicate is the ghost', async () => {
+    const [ghost, good] = [fileMeta('ghost'), fileMeta('good')];
+    stubCache([ghost, good]);
+    const provider = makeProvider(async (file) => {
+      if (file.fileId === 'ghost') throw notFound();
+      return jsonBlob(goodData);
+    });
+
+    const result = await svc.downloadVolumeDataFile(provider);
+
+    expect(result).toEqual(goodData);
+    expect(provider.deleteFile).toHaveBeenCalledTimes(1);
+    expect(provider.deleteFile).toHaveBeenCalledWith(ghost);
+  });
+
+  it('tolerates NOT_FOUND from deleting a ghost duplicate (already converged)', async () => {
+    const [good, ghost] = [fileMeta('good'), fileMeta('ghost')];
+    stubCache([good, ghost]);
+    const provider = makeProvider(
+      async (file) => {
+        if (file.fileId === 'ghost') throw notFound();
+        return jsonBlob(goodData);
+      },
+      async () => {
+        throw notFound();
+      }
+    );
+
+    await expect(svc.downloadVolumeDataFile(provider)).resolves.toEqual(goodData);
+  });
+
+  it('returns null after one cache refresh when every copy is missing', async () => {
+    const cache = stubCache([fileMeta('ghost-1'), fileMeta('ghost-2')]);
+    const provider = makeProvider(async () => {
+      throw notFound();
+    });
+
+    const result = await svc.downloadVolumeDataFile(provider);
+
+    expect(result).toBeNull();
+    expect(cache.fetch).toHaveBeenCalledTimes(1);
+    expect(provider.deleteFile).not.toHaveBeenCalled();
+  });
+
+  it('merges duplicates newest-lastProgressUpdate-wins and deletes the extra copy', async () => {
+    const [first, second] = [fileMeta('first'), fileMeta('second')];
+    stubCache([first, second]);
+    const newerData = {
+      'vol-1': { lastProgressUpdate: '2026-01-03T00:00:00Z', progress: 9 },
+      'vol-2': { lastProgressUpdate: '2026-01-01T00:00:00Z', progress: 1 }
+    };
+    const provider = makeProvider(async (file) =>
+      jsonBlob(file.fileId === 'first' ? goodData : newerData)
+    );
+
+    const result = await svc.downloadVolumeDataFile(provider);
+
+    expect(result['vol-1'].progress).toBe(9);
+    expect(result['vol-2'].progress).toBe(1);
+    expect(provider.deleteFile).toHaveBeenCalledTimes(1);
+    expect(provider.deleteFile).toHaveBeenCalledWith(second);
+  });
+
+  it('propagates transient download errors rather than treating them as missing data', async () => {
+    stubCache([fileMeta('good'), fileMeta('flaky')]);
+    const provider = makeProvider(async (file) => {
+      if (file.fileId === 'flaky') throw new Error('network down');
+      return jsonBlob(goodData);
+    });
+
+    await expect(svc.downloadVolumeDataFile(provider)).rejects.toThrow('network down');
+    expect(provider.deleteFile).not.toHaveBeenCalled();
+  });
+});