memorix 1.9.2 → 1.9.3

package/src/cli/commands/doctor.ts

@@ -283,11 +283,14 @@ export default defineCommand({
       let activeCount = 0;
       let ranCount = 0;
       let backendName = 'unknown';
+      let backendReason: string | undefined;
+      let observationFailure: string | undefined;
       try {
         const { initObservationStore, getObservationStore } = await import('../../store/obs-store.js');
         await initObservationStore(dataDir);
         const store = getObservationStore();
         backendName = store.getBackendName();
+        backendReason = store.getBackendReason?.();
         const { filterReadableObservations } = await import('../../memory/visibility.js');
         projectObservations = projectId
           ? filterReadableObservations(await store.loadAll(), { projectId })
@@ -295,12 +298,30 @@ export default defineCommand({
         obsCount = projectObservations.length;
         activeCount = projectObservations.filter((o: any) => (o.status ?? 'active') === 'active').length;
         ranCount = projectObservations.filter((o: any) => /^Ran:\s/i.test(o.title ?? '')).length;
-      } catch { /* ignore */ }
+      } catch (error) {
+        // The store could not be opened at all. Without this the counters stay
+        // at zero and the branch below reports "0 total" as a healthy result,
+        // which is indistinguishable from a project that has no observations.
+        observationFailure = error instanceof Error ? error.message : String(error);
+      }
 
-      if (backendName === 'degraded') {
-        lines.push(warn('Observations: SQLite unavailable — degraded (read-only, no data)'));
-        issues.push('SQLite backend unavailable — observations cannot be read or written.');
+      if (observationFailure) {
+        lines.push(fail(`Observations: storage unavailable — ${observationFailure}`));
+        issues.push(`Observation store could not be opened: ${observationFailure}`);
+        (report.data as any) = {
+          backend: 'unavailable',
+          observations: null,
+          active: null,
+          commandLogs: null,
+          error: observationFailure,
+        };
+      } else if (backendName === 'degraded') {
+        lines.push(fail(`Backend: degraded (read-only; writes disabled${backendReason ? `; ${backendReason}` : ''})`));
+        lines.push(fail('Observations: unavailable — count not reported'));
+        issues.push('SQLite backend unavailable — observation storage is in degraded read-only mode; observations are not being persisted.');
+        (report.data as any) = { backend: 'degraded', ...(backendReason ? { backendReason } : {}), observations: null, active: null, commandLogs: null };
       } else {
+        lines.push(ok('Backend: sqlite (read-write)'));
         lines.push(ok(`Observations: ${obsCount} total, ${activeCount} active`));
         if (ranCount > 0) {
           const pct = Math.round(ranCount / obsCount * 100);
@@ -310,32 +331,68 @@ export default defineCommand({
           }
         }
       }
-      report.data = { observations: obsCount, active: activeCount, commandLogs: ranCount };
+      if (!report.data) {
+        report.data = { backend: backendName, observations: obsCount, active: activeCount, commandLogs: ranCount };
+      } else if (!(report.data as any).backend) {
+        (report.data as any).backend = backendName;
+      }
 
       // Sessions — read from SQLite (canonical store)
+      let sessionBackend = 'unknown';
+      let sessionReason: string | undefined;
       try {
         const { initSessionStore, getSessionStore } = await import('../../store/session-store.js');
         await initSessionStore(dataDir);
         const sessStore = getSessionStore();
-        const sess = await sessStore.loadAll();
-        const sessCount = sess.length;
-        const activeSess = sess.filter((s: any) => s.status === 'active').length;
-        lines.push(ok(`Sessions: ${sessCount} total, ${activeSess} active`));
-        (report.data as any).sessions = sessCount;
-      } catch { /* ignore */ }
+        sessionBackend = sessStore.getBackendName();
+        sessionReason = sessStore.getBackendReason?.();
+        if (sessionBackend === 'degraded') {
+          lines.push(fail(`Sessions: unavailable — read-only degraded backend${sessionReason ? `; ${sessionReason}` : ''}`));
+          issues.push('Session storage is in degraded read-only mode.');
+          (report.data as any).sessions = null;
+          if (sessionReason) (report.data as any).sessionBackendReason = sessionReason;
+        } else {
+          const sess = await sessStore.loadAll();
+          const sessCount = sess.length;
+          const activeSess = sess.filter((s: any) => s.status === 'active').length;
+          lines.push(ok(`Sessions: ${sessCount} total, ${activeSess} active`));
+          (report.data as any).sessions = sessCount;
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        lines.push(fail(`Sessions: unavailable (${message})`));
+        issues.push(`Session storage is unavailable: ${message}`);
+        (report.data as any).sessions = null;
+      }
 
       // Mini-skills — read from SQLite (canonical store)
+      let skillBackend = 'unknown';
+      let skillReason: string | undefined;
       try {
         const { initMiniSkillStore, getMiniSkillStore } = await import('../../store/mini-skill-store.js');
         await initMiniSkillStore(dataDir);
         const skillStore = getMiniSkillStore();
-        const skills = await skillStore.loadAll();
-        const skillCount = skills.length;
-        if (skillCount > 0) {
-          lines.push(ok(`Mini-skills: ${skillCount}`));
-          (report.data as any).miniSkills = skillCount;
+        skillBackend = skillStore.getBackendName();
+        skillReason = skillStore.getBackendReason?.();
+        if (skillBackend === 'degraded') {
+          lines.push(fail(`Mini-skills: unavailable — read-only degraded backend${skillReason ? `; ${skillReason}` : ''}`));
+          issues.push('Mini-skill storage is in degraded read-only mode.');
+          (report.data as any).miniSkills = null;
+          if (skillReason) (report.data as any).miniSkillBackendReason = skillReason;
+        } else {
+          const skills = await skillStore.loadAll();
+          const skillCount = skills.length;
+          if (skillCount > 0) {
+            lines.push(ok(`Mini-skills: ${skillCount}`));
+            (report.data as any).miniSkills = skillCount;
+          }
         }
-      } catch { /* ignore */ }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        lines.push(fail(`Mini-skills: unavailable (${message})`));
+        issues.push(`Mini-skill storage is unavailable: ${message}`);
+        (report.data as any).miniSkills = null;
+      }
     } else {
       lines.push(warn('No data directory found for current project'));
       if (!projectId) {
@@ -633,5 +690,9 @@ export default defineCommand({
     } else {
       console.log(lines.join('\n'));
     }
+
+    if (issues.some((issue) => /^(Observation store could not be opened|Observation storage |Session storage |Mini-skill storage |SQLite backend unavailable)/.test(issue))) {
+      process.exitCode = 1;
+    }
   },
 });

package/src/store/mini-skill-store.ts

@@ -3,7 +3,7 @@
  *
  * Backends:
  *   - MiniSkillSqliteStore — canonical store, uses shared DB handle from sqlite-db.ts
- *   - MiniSkillGracefulDegrade — no-op fallback when SQLite is unavailable
+ *   - MiniSkillGracefulDegrade — explicit read-only fallback when SQLite is unavailable
  *
  * Phase 2 debt-zero: SQLite is the only canonical store for mini-skills.
  * JSON files are migration source only. No writable JSON fallback exists.
@@ -11,6 +11,7 @@
 
 import type { MiniSkill } from '../types.js';
 import { getDatabase } from './sqlite-db.js';
+import { degradedReadError, degradedWriteError, initializeSqliteStore, isSqliteUnavailableError, retrySqliteBusy } from './sqlite-reliability.js';
 import {
   loadMiniSkillsJson,
 } from './persistence.js';
@@ -36,6 +37,7 @@ export interface MiniSkillStore {
   ensureFresh(): Promise<boolean>;
   getGeneration(): number;
   getBackendName(): 'sqlite' | 'degraded';
+  getBackendReason?(): string | undefined;
 }
 
 // ── Row <-> MiniSkill serialization ─────────────────────────────────
@@ -220,7 +222,7 @@ export class MiniSkillSqliteStore implements MiniSkillStore {
    * SQLite serializes write transactions, so concurrent calls are safely sequenced.
    */
   async atomicInsertWithId(skillWithoutId: Omit<MiniSkill, 'id'>): Promise<MiniSkill> {
-    const result = this.db.transaction(() => {
+    return retrySqliteBusy(async () => this.db.transaction(() => {
       // 1. Read current counter inside the transaction
       const row = this.stmtGetMeta.get('mini_skills_next_id');
       const nextId = row ? parseInt(row.value, 10) : 1;
@@ -239,8 +241,7 @@ export class MiniSkillSqliteStore implements MiniSkillStore {
       this.knownGeneration = this.readGeneration();
 
       return skill;
-    })();
-    return result;
+    })(), 'Mini-skill promotion');
   }
 
   // ── Freshness ────────────────────────────────────────────────────
@@ -266,16 +267,21 @@ export class MiniSkillSqliteStore implements MiniSkillStore {
 // ── Graceful Degrade Fallback ────────────────────────────────────────
 //
 // Phase 2 debt-zero rule: mini-skills have NO writable JSON fallback.
-// In JSON-only environments (no better-sqlite3), reads return empty
-// and writes are no-ops with a warning. This prevents a parallel
-// canonical JSON write path from existing alongside SQLite.
+// In environments without a supported SQLite runtime, reads return an
+// explicit unavailable error and writes fail rather than pretending success.
 
 export class MiniSkillGracefulDegrade implements MiniSkillStore {
   private warned = false;
 
+  constructor(private readonly reason = 'SQLite runtime unavailable') {}
+
+  private unavailableRead(): Error {
+    return degradedReadError('mini-skills');
+  }
+
   private warn(): void {
     if (!this.warned) {
-      console.error('[memorix] MiniSkillStore: SQLite unavailable — mini-skills are disabled (read-only empty). Install better-sqlite3 for full functionality.');
+      console.error('[memorix] MiniSkillStore: SQLite unavailable — mini-skills cannot be read or written. Install a supported SQLite runtime.');
       this.warned = true;
     }
   }
@@ -284,22 +290,23 @@ export class MiniSkillGracefulDegrade implements MiniSkillStore {
     this.warn();
   }
 
-  async loadAll(): Promise<MiniSkill[]> { return []; }
-  async loadByProject(_projectId: string): Promise<MiniSkill[]> { return []; }
-  async loadIdCounter(): Promise<number> { return 1; }
+  async loadAll(): Promise<MiniSkill[]> { throw this.unavailableRead(); }
+  async loadByProject(_projectId: string): Promise<MiniSkill[]> { throw this.unavailableRead(); }
+  async loadIdCounter(): Promise<number> { throw this.unavailableRead(); }
 
-  async insert(_skill: MiniSkill): Promise<void> { this.warn(); }
-  async update(_skill: MiniSkill): Promise<void> { this.warn(); }
-  async remove(_id: number): Promise<void> { this.warn(); }
-  async saveIdCounter(_nextId: number): Promise<void> { /* no-op */ }
+  async insert(_skill: MiniSkill): Promise<void> { this.warn(); throw degradedWriteError('mini-skills'); }
+  async update(_skill: MiniSkill): Promise<void> { this.warn(); throw degradedWriteError('mini-skills'); }
+  async remove(_id: number): Promise<void> { this.warn(); throw degradedWriteError('mini-skills'); }
+  async saveIdCounter(_nextId: number): Promise<void> { this.warn(); throw degradedWriteError('mini-skills'); }
   async atomicInsertWithId(skillWithoutId: Omit<MiniSkill, 'id'>): Promise<MiniSkill> {
     this.warn();
-    return { ...skillWithoutId, id: 0 } as MiniSkill;
+    throw degradedWriteError('mini-skills');
   }
 
   async ensureFresh(): Promise<boolean> { return false; }
   getGeneration(): number { return 0; }
   getBackendName(): 'sqlite' | 'degraded' { return 'degraded'; }
+  getBackendReason(): string { return this.reason; }
 }
 
 // ── Singleton access ────────────────────────────────────────────────
@@ -329,19 +336,21 @@ export async function initMiniSkillStore(dataDir: string): Promise<MiniSkillStor
   _store = null;
   _storeDataDir = null;
 
-  // Try SQLite first
+  // Only a missing SQLite runtime may use the intentional read-only fallback.
+  let degradedReason = 'SQLite runtime unavailable';
   try {
-    const store = new MiniSkillSqliteStore();
-    await store.init(dataDir);
+    const store = await initializeSqliteStore(() => new MiniSkillSqliteStore(), dataDir, 'Mini-skill store');
     _store = store;
     _storeDataDir = dataDir;
     return store;
   } catch (err) {
-    console.error(`[memorix] MiniSkillSqliteStore unavailable, running in degraded read-only mode: ${err instanceof Error ? err.message : err}`);
+    if (!isSqliteUnavailableError(err)) throw err;
+    degradedReason = err instanceof Error ? err.message : String(err);
+    console.error(`[memorix] MiniSkillSqliteStore unavailable, running in degraded read-only mode: ${degradedReason}`);
   }
 
-  // Fallback: graceful degrade (no writable JSON backend per debt-zero rule)
-  const store = new MiniSkillGracefulDegrade();
+  // Fallback: explicit read-only mode (no writable JSON backend per debt-zero rule)
+  const store = new MiniSkillGracefulDegrade(degradedReason);
   await store.init(dataDir);
   _store = store;
   _storeDataDir = dataDir;

package/src/store/obs-store.ts

@@ -3,7 +3,7 @@
  *
  * Backends:
  *   - SqliteBackend (sqlite-store.ts) — WAL-mode SQLite with generation tracking
- *   - DegradedBackend — read-only empty store when SQLite is unavailable
+ *   - DegradedBackend — diagnostic-only backend when SQLite is unavailable
  *
  * JSON is no longer a runtime writable backend.
  * observations.json is only used as a one-time migration source into SQLite.
@@ -12,6 +12,7 @@
  */
 
 import type { Observation } from '../types.js';
+import { degradedReadError, degradedWriteError, formatSqliteFailure, isSqliteUnavailableError, initializeSqliteStore } from './sqlite-reliability.js';
 
 /**
  * Raw transaction handle for compound atomic operations.
@@ -164,6 +165,9 @@ export interface ObservationStore {
 
   /** Which backend is active: 'sqlite' or 'degraded' (read-only). */
   getBackendName(): 'sqlite' | 'degraded';
+
+  /** Why a degraded backend was selected, when applicable. */
+  getBackendReason?(): string | undefined;
 }
 
 // ── Singleton store access ─────────────────────────────────────────
@@ -199,23 +203,25 @@ export function resetObservationStore(): void {
  * without touching the process-wide singleton. This is useful for long-lived
  * multi-project hosts (for example serve-http embedded dashboard APIs) where
  * requests may need to read different project data dirs concurrently.
+ *
+ * Only a *structural* failure — better-sqlite3 genuinely unavailable — falls
+ * back to the read-only DegradedBackend. A transient lock is retried, and a
+ * persistent runtime failure is thrown rather than silently degraded: an
+ * empty-looking store is far more dangerous than a loud error, because
+ * callers cannot distinguish it from a project with no observations yet.
  */
 export async function createObservationStore(dataDir: string): Promise<ObservationStore> {
-  // Try SQLite first (optionalDependencies — may not be installed)
   try {
     const { SqliteBackend } = await import('./sqlite-store.js');
-    const store = new SqliteBackend();
-    await store.init(dataDir);
-    return store;
+    return await initializeSqliteStore(() => new SqliteBackend(), dataDir, 'Observation store');
   } catch (err) {
-    console.error(`[memorix] SQLite backend unavailable — degraded mode (read-only): ${err instanceof Error ? err.message : err}`);
+    if (!isSqliteUnavailableError(err)) throw err;
+    const reason = formatSqliteFailure(err);
+    console.error(`[memorix] SQLite module unavailable — degraded mode (reads/writes disabled): ${reason}`);
+    const degraded = new DegradedBackend(reason);
+    await degraded.init(dataDir);
+    return degraded;
   }
-
-  // No writable JSON fallback — degraded read-only mode instead
-  // observations.json is only used as migration source, not runtime backend
-  const store = new DegradedBackend();
-  await store.init(dataDir);
-  return store;
 }
 
 /**
@@ -243,52 +249,58 @@ export async function initObservationStore(dataDir: string): Promise<Observation
   return store;
 }
 
-// ── DegradedBackend (read-only when SQLite unavailable) ──────────
+// ── DegradedBackend (diagnostic-only when SQLite unavailable) ─────
 
 /**
- * DegradedBackend — ObservationStore that is read-only and empty.
+ * DegradedBackend — diagnostic-only backend used when SQLite is unavailable.
  *
- * Used when better-sqlite3 is unavailable. All write operations throw.
+ * Business reads and writes throw instead of returning synthetic empty data.
  * This ensures the system does not silently fall back to writing observations.json
  * as a runtime canonical store.
  */
 export class DegradedBackend implements ObservationStore {
   private dataDir: string = '';
 
+  constructor(private readonly reason = 'SQLite runtime unavailable') {}
+
+  private unavailableRead(): Error {
+    return degradedReadError('observations');
+  }
+
   async init(dataDir: string): Promise<void> {
     this.dataDir = dataDir;
   }
 
   async loadAll(): Promise<Observation[]> {
-    return [];
+    throw this.unavailableRead();
   }
 
   async loadByProject(_projectId: string, _options?: { status?: string; limit?: number; offset?: number; afterId?: number; newestFirst?: boolean }): Promise<Observation[]> {
-    return [];
+    throw this.unavailableRead();
   }
 
   async countByProject(_projectId: string, _options?: { status?: string; visibility?: 'project' }): Promise<number> {
-    return 0;
+    throw this.unavailableRead();
   }
 
   async getById(_id: number): Promise<Observation | undefined> {
-    return undefined;
+    throw this.unavailableRead();
   }
 
   async loadIdCounter(): Promise<number> {
-    return 1;
+    throw this.unavailableRead();
   }
 
   async countAll(): Promise<number> {
-    return 0;
+    throw this.unavailableRead();
   }
 
   async listProjectIds(): Promise<string[]> {
-    return [];
+    throw this.unavailableRead();
   }
 
   async searchLexical(_options: LexicalSearchOptions): Promise<LexicalSearchHit[]> {
-    return [];
+    throw this.unavailableRead();
   }
 
   hasLexicalIndex(): boolean {
@@ -300,31 +312,31 @@ export class DegradedBackend implements ObservationStore {
   }
 
   async insert(_obs: Observation): Promise<void> {
-    throw new Error('[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)');
+    throw degradedWriteError('observations');
   }
 
   async update(_obs: Observation): Promise<void> {
-    throw new Error('[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)');
+    throw degradedWriteError('observations');
   }
 
   async remove(_id: number): Promise<void> {
-    throw new Error('[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)');
+    throw degradedWriteError('observations');
   }
 
   async bulkReplace(_obs: Observation[]): Promise<void> {
-    throw new Error('[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)');
+    throw degradedWriteError('observations');
   }
 
   async bulkRemoveByIds(_ids: number[]): Promise<void> {
-    throw new Error('[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)');
+    throw degradedWriteError('observations');
   }
 
   async saveIdCounter(_nextId: number): Promise<void> {
-    throw new Error('[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)');
+    throw degradedWriteError('observations');
   }
 
   async atomic<T>(_fn: (tx: StoreTransaction) => Promise<T>): Promise<T> {
-    throw new Error('[memorix] Cannot write observations: SQLite backend unavailable (degraded mode)');
+    throw degradedWriteError('observations');
   }
 
   async ensureFresh(): Promise<boolean> {
@@ -342,4 +354,8 @@ export class DegradedBackend implements ObservationStore {
   getBackendName(): 'sqlite' | 'degraded' {
     return 'degraded';
   }
+
+  getBackendReason(): string {
+    return this.reason;
+  }
 }

package/src/store/session-store.ts

@@ -3,7 +3,7 @@
  *
  * Backends:
  *   - SessionSqliteStore — canonical store, uses shared DB handle from sqlite-db.ts
- *   - SessionGracefulDegrade — no-op fallback when SQLite is unavailable
+ *   - SessionGracefulDegrade — explicit read-only fallback when SQLite is unavailable
  *
  * Phase 2 debt-zero: SQLite is the only canonical store for sessions.
  * JSON files are migration source only. No writable JSON fallback exists.
@@ -11,6 +11,7 @@
 
 import type { Session } from '../types.js';
 import { getDatabase } from './sqlite-db.js';
+import { degradedReadError, degradedWriteError, formatSqliteFailure, initializeSqliteStore, isSqliteUnavailableError, retrySqliteBusy } from './sqlite-reliability.js';
 import { loadSessionsJson } from './persistence.js';
 import path from 'node:path';
 import fs from 'node:fs';
@@ -33,6 +34,7 @@ export interface SessionStoreInterface {
    */
   atomicRolloverInsert(newSession: Session, projectIds: string[], now: string): Promise<number>;
   getBackendName(): 'sqlite' | 'degraded';
+  getBackendReason?(): string | undefined;
 }
 
 // ── Row <-> Session serialization ───────────────────────────────────
@@ -175,7 +177,7 @@ export class SessionSqliteStore implements SessionStoreInterface {
     const stmtComplete = this._stmtCompleteActive;
     const stmtIns = this.stmtInsert;
 
-    const result = this.db.transaction(() => {
+    return retrySqliteBusy(async () => this.db.transaction(() => {
       let completedCount = 0;
       for (const pid of projectIds) {
         const info = stmtComplete.run({ pid, now });
@@ -183,8 +185,7 @@ export class SessionSqliteStore implements SessionStoreInterface {
       }
       stmtIns.run(sessionToRow(newSession));
       return completedCount;
-    })();
-    return result;
+    })(), 'Session rollover');
   }
 
   getBackendName(): 'sqlite' | 'degraded' {
@@ -195,15 +196,21 @@ export class SessionSqliteStore implements SessionStoreInterface {
 // ── Graceful Degrade Fallback ────────────────────────────────────────
 //
 // Phase 2 debt-zero rule: sessions have NO writable JSON fallback.
-// In JSON-only environments (no better-sqlite3), reads return empty
-// and writes are no-ops with a warning.
+// In environments without a supported SQLite runtime, reads return an
+// explicit unavailable error and writes fail rather than pretending success.
 
 export class SessionGracefulDegrade implements SessionStoreInterface {
   private warned = false;
 
+  constructor(private readonly reason = 'SQLite runtime unavailable') {}
+
+  private unavailableRead(): Error {
+    return degradedReadError('sessions');
+  }
+
   private warn(): void {
     if (!this.warned) {
-      console.error('[memorix] SessionStore: SQLite unavailable — sessions are disabled (read-only empty). Install better-sqlite3 for full functionality.');
+      console.error('[memorix] SessionStore: SQLite unavailable — sessions cannot be read or written. Install a supported SQLite runtime.');
       this.warned = true;
     }
   }
@@ -212,17 +219,22 @@ export class SessionGracefulDegrade implements SessionStoreInterface {
     this.warn();
   }
 
-  async loadAll(): Promise<Session[]> { return []; }
-  async getById(_id: string): Promise<Session | undefined> { return undefined; }
-  async loadByProject(_projectId: string): Promise<Session[]> { return []; }
-  async loadActive(_projectId: string): Promise<Session[]> { return []; }
+  async loadAll(): Promise<Session[]> { throw this.unavailableRead(); }
+  async getById(_id: string): Promise<Session | undefined> { throw this.unavailableRead(); }
+  async loadByProject(_projectId: string): Promise<Session[]> { throw this.unavailableRead(); }
+  async loadActive(_projectId: string): Promise<Session[]> { throw this.unavailableRead(); }
 
-  async insert(_session: Session): Promise<void> { this.warn(); }
-  async update(_session: Session): Promise<void> { this.warn(); }
-  async bulkUpdate(_sessions: Session[]): Promise<void> { this.warn(); }
-  async atomicRolloverInsert(_newSession: Session, _projectIds: string[], _now: string): Promise<number> { this.warn(); return 0; }
+  async insert(_session: Session): Promise<void> { this.warn(); throw degradedWriteError('sessions'); }
+  async update(_session: Session): Promise<void> { this.warn(); throw degradedWriteError('sessions'); }
+  async bulkUpdate(_sessions: Session[]): Promise<void> { this.warn(); throw degradedWriteError('sessions'); }
+  async atomicRolloverInsert(_newSession: Session, _projectIds: string[], _now: string): Promise<number> {
+    this.warn();
+    throw degradedWriteError('sessions');
+  }
 
   getBackendName(): 'sqlite' | 'degraded' { return 'degraded'; }
+
+  getBackendReason(): string { return this.reason; }
 }
 
 // ── Singleton access ────────────────────────────────────────────────
@@ -248,19 +260,21 @@ export async function initSessionStore(dataDir: string): Promise<SessionStoreInt
   _store = null;
   _storeDataDir = null;
 
-  // Try SQLite first
+  // Only a missing SQLite runtime may use the intentional read-only fallback.
+  let degradedReason = 'SQLite runtime unavailable';
   try {
-    const store = new SessionSqliteStore();
-    await store.init(dataDir);
+    const store = await initializeSqliteStore(() => new SessionSqliteStore(), dataDir, 'Session store');
     _store = store;
     _storeDataDir = dataDir;
     return store;
   } catch (err) {
-    console.error(`[memorix] SessionSqliteStore unavailable, running in degraded read-only mode: ${err instanceof Error ? err.message : err}`);
+    if (!isSqliteUnavailableError(err)) throw err;
+    degradedReason = formatSqliteFailure(err);
+    console.error(`[memorix] SessionSqliteStore unavailable, running in degraded read-only mode: ${degradedReason}`);
   }
 
-  // Fallback: graceful degrade (no writable JSON backend per debt-zero rule)
-  const store = new SessionGracefulDegrade();
+  // Fallback: explicit read-only mode (no writable JSON backend per debt-zero rule)
+  const store = new SessionGracefulDegrade(degradedReason);
   await store.init(dataDir);
   _store = store;
   _storeDataDir = dataDir;

package/src/store/sqlite-db.ts

@@ -1126,12 +1126,15 @@ export function getDatabase(dataDir: string): any {
   fs.mkdirSync(dataDir, { recursive: true });
 
   const dbPath = path.join(dataDir, 'memorix.db');
-  const db = createDatabase(dbPath);
+  let db: any;
+  try {
+    db = createDatabase(dbPath);
 
-  // WAL mode for concurrent read performance
-  db.pragma('journal_mode = WAL');
-  db.pragma('busy_timeout = 5000');
-  db.pragma('foreign_keys = ON');
+    // Set the connection-local wait policy before the journal-mode transition.
+    db.pragma('busy_timeout = 5000');
+    // WAL allows readers to continue while one short writer transaction runs.
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
 
   // Create all tables
   db.exec(CREATE_OBSERVATIONS_TABLE);
@@ -1188,8 +1191,14 @@ export function getDatabase(dataDir: string): any {
   db.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('next_id', '1')`).run();
   db.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('mini_skills_generation', '0')`).run();
 
-  _dbCache.set(normalized, db);
-  return db;
+    _dbCache.set(normalized, db);
+    return db;
+  } catch (error) {
+    // A schema/migration/FTS failure must not leave an uncached connection
+    // holding a file lock while callers retry initialization.
+    try { db?.close(); } catch { /* best-effort cleanup */ }
+    throw error;
+  }
 }
 
 /**