feat: surface startup restore failures with an aggregated notice (#24)

Add restore diagnostics: a windowed collector gathers issues from the
four restore stages (layout, tab, metadata, history) during startup and
the chat view drains them into a single aggregated notice. Each issue is
also logged to the developer console with a stage prefix.

- Report layout read failures, per-tab rebuild failures, session
  metadata read failures, and history hydration gaps instead of failing
  silently; first-run vaults with no data never report.
- Deduplicate repeated issues so the notice count reflects real root
  causes, and always close the report window from the restore path.
- Add localized notice copy in all ten languages and CHANGELOG entry.

Co-authored-by: QoderAI (Qwen 3.8 Max) <qoder_ai@qoder.com>

Author: luoxuanzao

CHANGELOG.md

@@ -45,6 +45,10 @@ version with its date and start a fresh empty `[Unreleased]` above it.
   collapse), the toolbar wraps instead of clipping, and the permission
   mode and model dropdowns shrink to stay inside the sidebar, with
   long model names ellipsized.
+- Startup session restore no longer fails silently: when the tab
+  layout, an individual tab, session metadata, or conversation history
+  cannot be read, Qoderian now shows a single notice with the issue
+  count and logs per-stage details to the developer console.
 
 ## [1.0.4] - 2026-08-12
 

src/app/storage/app-storage.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from 'obsidian';
 import { Notice } from 'obsidian';
 
+import { reportRestoreIssue } from '../../core/diagnostics/restore-report';
 import { VaultFileAdapter } from '../../core/storage/vault-file-adapter';
 import type { AppTabManagerState } from '../../core/types/services';
 import {
@@ -14,6 +15,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === 'object' && !Array.isArray(value);
 }
 
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 export class QoderianStorage {
   readonly qoderianSettings: QoderianSettingsStorage;
   readonly sessions: SessionStorage;
@@ -62,11 +67,17 @@ export class QoderianStorage {
     try {
       const data: unknown = await this.plugin.loadData();
       if (!isRecord(data) || !data.tabManagerState) {
+        await this.reportUnreadablePluginData();
         return null;
       }
 
-      return this.validateTabManagerState(data.tabManagerState);
-    } catch {
+      const state = this.validateTabManagerState(data.tabManagerState);
+      if (!state) {
+        reportRestoreIssue('layout', 'Persisted tab layout failed validation.');
+      }
+      return state;
+    } catch (error) {
+      reportRestoreIssue('layout', `Failed to read persisted tab layout: ${errorMessage(error)}`);
       return null;
     }
   }
@@ -75,6 +86,26 @@ export class QoderianStorage {
     return this.adapter;
   }
 
+  /**
+   * Obsidian may return null from loadData for corrupt JSON instead of
+   * throwing; a non-empty raw data file therefore means unreadable content.
+   */
+  private async reportUnreadablePluginData(): Promise<void> {
+    const pluginId = this.plugin.manifest?.id ?? 'qoderian';
+    const dataPath = `${this.plugin.app.vault.configDir}/plugins/${pluginId}/data.json`;
+    try {
+      const raw = await this.adapter.read(dataPath);
+      if (raw.trim().length > 0) {
+        reportRestoreIssue(
+          'layout',
+          `Plugin data file "${dataPath}" could not be read; loaded an empty layout instead.`,
+        );
+      }
+    } catch {
+      // Missing file: first run, nothing to report.
+    }
+  }
+
   private async ensureDirectories(): Promise<void> {
     await this.adapter.ensureFolder(QODERIAN_STORAGE_PATH);
     await this.adapter.ensureFolder(SESSIONS_PATH);

src/app/storage/session-storage.ts

@@ -1,3 +1,4 @@
+import { reportRestoreIssue } from '../../core/diagnostics/restore-report';
 import type { VaultFileAdapter } from '../../core/storage/vault-file-adapter';
 import type { SessionMetadata } from '../../core/types';
 import { SESSIONS_PATH } from './storage-paths';
@@ -21,7 +22,8 @@ export class SessionStorage {
     try {
       const content = await this.adapter.read(this.getMetadataPath(id));
       return JSON.parse(content) as SessionMetadata;
-    } catch {
+    } catch (error) {
+      reportRestoreIssue('metadata', `Failed to read session metadata "${id}": ${errorMessage(error)}`);
       return null;
     }
   }
@@ -37,8 +39,9 @@ export class SessionStorage {
       try {
         const content = await this.adapter.read(filePath);
         metas.push(JSON.parse(content) as SessionMetadata);
-      } catch {
-        // Skip files that fail to load.
+      } catch (error) {
+        // Skip files that fail to load, but surface the skip.
+        reportRestoreIssue('metadata', `Failed to read session metadata file "${filePath}": ${errorMessage(error)}`);
       }
     }
 
@@ -49,8 +52,13 @@ export class SessionStorage {
     try {
       const files = await this.adapter.listFiles(SESSIONS_PATH);
       return files.filter((filePath) => filePath.endsWith('.meta.json'));
-    } catch {
+    } catch (error) {
+      reportRestoreIssue('metadata', `Failed to list session metadata files: ${errorMessage(error)}`);
       return [];
     }
   }
 }
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

src/core/diagnostics/restore-report.ts

@@ -0,0 +1,52 @@
+/**
+ * Startup restore diagnostics.
+ *
+ * The restore pipeline (tab layout read, per-tab rebuild, session metadata,
+ * conversation history hydration) used to swallow failures silently, leaving
+ * users with missing tabs or empty conversations and no explanation. Each
+ * stage reports issues here; the chat view drains the collected issues once
+ * restore finishes and surfaces a single aggregated notice.
+ */
+
+export type RestoreStage = 'layout' | 'tab' | 'metadata' | 'history';
+
+export interface RestoreIssue {
+  stage: RestoreStage;
+  detail: string;
+}
+
+let activeIssues: RestoreIssue[] | null = null;
+
+/** Opens the collection window (called once on plugin load). */
+export function beginRestoreReport(): void {
+  activeIssues = [];
+}
+
+/**
+ * Records a restore issue. Always logged for debugging; only collected into
+ * the user-facing report while the window is open.
+ */
+export function reportRestoreIssue(stage: RestoreStage, detail: string): void {
+  console.error(`[qoderian-restore:${stage}] ${detail}`);
+  activeIssues?.push({ stage, detail });
+}
+
+/**
+ * Closes the window (restore finished) and returns the collected issues.
+ * Duplicates are dropped: some stages run twice during startup (e.g. the
+ * tab layout is read by both loadSettings and the chat view), and counting
+ * the same root cause twice would inflate the aggregated notice.
+ */
+export function finishRestoreReport(): RestoreIssue[] {
+  const issues = activeIssues ?? [];
+  activeIssues = null;
+  const seen = new Set<string>();
+  return issues.filter((issue) => {
+    const key = `${issue.stage}:${issue.detail}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}

src/features/chat/chat-view.ts

@@ -1,7 +1,9 @@
 import type { EventRef, WorkspaceLeaf } from 'obsidian';
 import { ItemView, Notice, Scope, setIcon } from 'obsidian';
 
+import { finishRestoreReport } from '../../core/diagnostics/restore-report';
 import { VIEW_TYPE_QODERIAN } from '../../core/types';
+import { t } from '../../i18n/i18n';
 import type QoderianPlugin from '../../main';
 import { fetchCreditsUsage } from '../../qoder/services/credits-usage';
 import {
@@ -607,17 +609,24 @@ export class QoderianView extends ItemView {
   // ============================================
 
   private async restoreOrCreateTabs(): Promise<void> {
-    if (!this.tabManager) return;
-
-    // Try to restore from persisted state
-    const persistedState = await this.plugin.storage.getTabManagerState();
-    if (persistedState && persistedState.openTabs.length > 0) {
-      await this.tabManager.restoreState(persistedState);
-      return;
+    try {
+      if (!this.tabManager) return;
+
+      // Try to restore from persisted state
+      const persistedState = await this.plugin.storage.getTabManagerState();
+      if (persistedState && persistedState.openTabs.length > 0) {
+        await this.tabManager.restoreState(persistedState);
+      } else {
+        // Fallback: create a new empty tab
+        await this.tabManager.createTab();
+      }
+    } finally {
+      // Drain startup restore diagnostics and surface them once, aggregated.
+      const issues = finishRestoreReport();
+      if (issues.length > 0) {
+        new Notice(t('restore.failed', { count: issues.length }), 10000);
+      }
     }
-
-    // Fallback: create a new empty tab
-    await this.tabManager.createTab();
   }
 
   /**

src/features/chat/tabs/tab-manager.ts

@@ -1,5 +1,6 @@
 import { Notice } from 'obsidian';
 
+import { reportRestoreIssue } from '../../../core/diagnostics/restore-report';
 import type { ChatRuntime } from '../../../core/runtime/chat-runtime';
 import { t } from '../../../i18n/i18n';
 import type QoderianPlugin from '../../../main';
@@ -537,8 +538,9 @@ export class TabManager implements TabManagerInterface {
             activate: false,
             ...(typeof tabState.draftModel === 'string' ? { draftModel: tabState.draftModel } : {}),
           });
-        } catch {
-          // Continue restoring other tabs
+        } catch (error) {
+          // Continue restoring other tabs, but surface the skipped one.
+          reportRestoreIssue('tab', `Failed to restore tab "${tabState.tabId}": ${errorMessage(error)}`);
         }
       }
     } finally {
@@ -557,8 +559,8 @@ export class TabManager implements TabManagerInterface {
     if (targetTabId) {
       try {
         await this.switchToTab(targetTabId);
-      } catch {
-        // Ignore switch errors
+      } catch (error) {
+        reportRestoreIssue('tab', `Failed to activate restored tab "${targetTabId}": ${errorMessage(error)}`);
       }
     }
 
@@ -634,3 +636,7 @@ export class TabManager implements TabManagerInterface {
     this.activeTabId = null;
   }
 }
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

src/i18n/locales/de.json

@@ -25,6 +25,9 @@
     "send": "Nachricht senden",
     "stop": "Generierung stoppen"
   },
+  "restore": {
+    "failed": "Einige Tabs oder Unterhaltungen konnten nicht wiederhergestellt werden ({count} Problem(e)). Details in der Entwicklerkonsole."
+  },
   "commands": {
     "openView": "Chat-Ansicht öffnen",
     "inlineEdit": "Inline-Bearbeitung",

src/i18n/locales/en.json

@@ -25,6 +25,9 @@
     "send": "Send message",
     "stop": "Stop generation"
   },
+  "restore": {
+    "failed": "Some of your previous tabs or conversations could not be restored ({count} issue(s)). Details are in the developer console."
+  },
   "commands": {
     "openView": "Open chat view",
     "inlineEdit": "Inline edit",

src/i18n/locales/es.json

@@ -25,6 +25,9 @@
     "send": "Enviar mensaje",
     "stop": "Detener generación"
   },
+  "restore": {
+    "failed": "No se pudieron restaurar algunas pestañas o conversaciones ({count} problema(s)). Detalles en la consola de desarrollador."
+  },
   "commands": {
     "openView": "Abrir vista de chat",
     "inlineEdit": "Edición en línea",

src/i18n/locales/fr.json

@@ -25,6 +25,9 @@
     "send": "Envoyer le message",
     "stop": "Arrêter la génération"
   },
+  "restore": {
+    "failed": "Certains onglets ou conversations n'ont pas pu être restaurés ({count} problème(s)). Détails dans la console développeur."
+  },
   "commands": {
     "openView": "Ouvrir la vue de discussion",
     "inlineEdit": "Édition en ligne",