agentic-qe 3.15.14 → 3.15.16

package/dist/integrations/agentic-flow/reasoning-bank/trajectory-tracker.js

@@ -75,7 +75,7 @@ export class TrajectoryTracker {
         // Load recent trajectories into buffer
         await this.loadRecentTrajectories();
         // Clean up orphaned trajectories from previous sessions (started > 1 hour ago, never completed)
-        this.cleanupOrphanedTrajectories();
+        await this.cleanupOrphanedTrajectories();
         this.initialized = true;
         console.log('[TrajectoryTracker] Initialized');
     }
@@ -83,18 +83,20 @@ export class TrajectoryTracker {
      * Clean up orphaned trajectories that were started but never completed.
      * Marks them as failed with an auto-close reason. Runs at initialization.
      */
-    cleanupOrphanedTrajectories() {
-        if (!this.db)
+    async cleanupOrphanedTrajectories() {
+        const db = this.db;
+        if (!db || !this.unifiedMemory)
             return;
         try {
-            const result = this.db.prepare(`
+            // #1263: retried asynchronously, so a locked DB does not freeze the MCP server.
+            const result = await this.unifiedMemory.writeWhenUnlocked(() => db.prepare(`
         UPDATE qe_trajectories
         SET success = 0,
             ended_at = datetime('now'),
             feedback = 'auto-closed: orphaned trajectory from previous session'
         WHERE success IS NULL
           AND started_at < datetime('now', '-1 hour')
-      `).run();
+      `).run());
             if (result.changes > 0) {
                 this.stats.trajectoriesAbandoned += result.changes;
                 console.log(`[TrajectoryTracker] Cleaned up ${result.changes} orphaned trajectories`);
@@ -238,10 +240,13 @@ export class TrajectoryTracker {
             startedAt,
             context: options.context,
         });
-        // Persist to SQLite
+        // Persist to SQLite. Queued (#1283): task_orchestrate starts a trajectory
+        // inside the tool call, and a locked memory.db must not freeze the MCP
+        // server's event loop. The later end update queues after this insert.
         const insertStmt = this.prepared.get('insertTrajectory');
         if (insertStmt) {
-            insertStmt.run(id, task, options.agent || null, options.domain || null, startedAt.toISOString(), options.context ? JSON.stringify(options.context) : null);
+            const run = () => insertStmt.run(id, task, options.agent || null, options.domain || null, startedAt.toISOString(), options.context ? JSON.stringify(options.context) : null);
+            await (this.unifiedMemory ? this.unifiedMemory.writeWhenUnlocked(run) : run());
         }
         this.stats.trajectoriesStarted++;
         // Set auto-end timeout
@@ -344,12 +349,15 @@ export class TrajectoryTracker {
             endedAt,
             feedback,
         };
-        // Persist to SQLite
+        // Persist to SQLite. Queued (#1274): task completion events end
+        // trajectories in the background, and a locked memory.db must not freeze
+        // the MCP server's event loop.
         const updateStmt = this.prepared.get('updateTrajectory');
         if (updateStmt) {
-            updateStmt.run(endedAt.toISOString(), success ? 1 : 0, JSON.stringify(active.steps), JSON.stringify({ metrics, context: active.context }), null, // embedding - computed later if needed
+            const run = () => updateStmt.run(endedAt.toISOString(), success ? 1 : 0, JSON.stringify(active.steps), JSON.stringify({ metrics, context: active.context }), null, // embedding - computed later if needed
             feedback ?? null, null, // related_patterns - computed later
             trajectoryId);
+            await (this.unifiedMemory ? this.unifiedMemory.writeWhenUnlocked(run) : run());
         }
         // Remove from active, add to recent buffer
         this.activeTrajectories.delete(trajectoryId);

package/dist/integrations/embeddings/cache/EmbeddingCache.d.ts

@@ -84,6 +84,14 @@ export declare class EmbeddingCache {
      * Persist entry to disk
      */
     private persistToDisk;
+    /**
+     * Run a write on the cache's connection without blocking the caller
+     * (#1283). On the shared memory.db connection it goes through the write
+     * queue, so a locked database does not freeze the MCP server's event loop;
+     * on a private (legacy) connection it runs at once. A failure is logged,
+     * since the in-memory cache is already up to date.
+     */
+    private persist;
     /**
      * Flush writes that were queued during async DB initialization
      */

package/dist/integrations/embeddings/cache/EmbeddingCache.js

@@ -24,6 +24,7 @@ import { join } from 'path';
 import { existsSync, mkdirSync } from 'fs';
 import { getUnifiedMemory, findProjectRoot } from '../../../kernel/unified-memory.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { writeWhenUnlockedOn } from '../../../shared/sqlite-write-queue.js';
 /**
  * Embedding cache with LRU eviction and persistent storage
  */
@@ -183,8 +184,7 @@ export class EmbeddingCache {
         const cache = this.memoryCache.get(namespace);
         const deleted = cache?.delete(key) || false;
         if (deleted && this.persistent && this.db) {
-            const stmt = this.db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?');
-            stmt.run(key, namespace);
+            this.persist('delete', (db) => db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?').run(key, namespace));
         }
         return deleted;
     }
@@ -196,8 +196,7 @@ export class EmbeddingCache {
             const cache = this.memoryCache.get(namespace);
             cache?.clear();
             if (this.persistent && this.db) {
-                const stmt = this.db.prepare('DELETE FROM embeddings WHERE namespace = ?');
-                stmt.run(namespace);
+                this.persist('clear', (db) => db.prepare('DELETE FROM embeddings WHERE namespace = ?').run(namespace));
             }
         }
         else {
@@ -205,7 +204,7 @@ export class EmbeddingCache {
                 cache.clear();
             }
             if (this.persistent && this.db) {
-                this.db.exec('DELETE FROM embeddings');
+                this.persist('clear', (db) => db.exec('DELETE FROM embeddings'));
             }
         }
     }
@@ -243,8 +242,8 @@ export class EmbeddingCache {
         if (lruKey) {
             cache.delete(lruKey);
             if (this.persistent && this.db) {
-                const stmt = this.db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?');
-                stmt.run(lruKey, namespace);
+                const evicted = lruKey;
+                this.persist('evict', (db) => db.prepare('DELETE FROM embeddings WHERE key = ? AND namespace = ?').run(evicted, namespace));
             }
         }
     }
@@ -259,17 +258,32 @@ export class EmbeddingCache {
             const metadataJson = embedding.metadata
                 ? JSON.stringify(embedding.metadata)
                 : null;
-            const stmt = this.db.prepare(`
+            const lastAccess = Date.now();
+            this.persist('persist', (db) => db.prepare(`
         INSERT OR REPLACE INTO embeddings
         (key, namespace, vector, dimension, text, timestamp, quantization, metadata, last_access)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `);
-            stmt.run(key, namespace, vectorBuffer, embedding.dimension, embedding.text, embedding.timestamp, embedding.quantization, metadataJson, Date.now());
+      `).run(key, namespace, vectorBuffer, embedding.dimension, embedding.text, embedding.timestamp, embedding.quantization, metadataJson, lastAccess));
         }
         catch (error) {
             console.warn('Failed to persist embedding:', error);
         }
     }
+    /**
+     * Run a write on the cache's connection without blocking the caller
+     * (#1283). On the shared memory.db connection it goes through the write
+     * queue, so a locked database does not freeze the MCP server's event loop;
+     * on a private (legacy) connection it runs at once. A failure is logged,
+     * since the in-memory cache is already up to date.
+     */
+    persist(action, write) {
+        const db = this.db;
+        if (!db)
+            return;
+        writeWhenUnlockedOn(db, () => write(db)).catch((error) => {
+            console.warn(`Failed to ${action} embedding cache entry:`, error);
+        });
+    }
     /**
      * Flush writes that were queued during async DB initialization
      */

package/dist/integrations/ruvector/delta-tracker.d.ts

@@ -77,6 +77,17 @@ export declare class DeltaTracker {
     initialize(): void;
     private prepareStatements;
     private ensureInitialized;
+    /**
+     * createGenesis() through the shared connection's write queue (#1283). The
+     * version check and the insert run as one queued unit.
+     */
+    createGenesisWhenUnlocked(patternId: string, snapshot: object, metadata?: Record<string, unknown>): Promise<DeltaEvent>;
+    /**
+     * recordDelta() through the shared connection's write queue (#1283). Reading
+     * the current version, the insert and retention run as one queued unit, so
+     * two deltas cannot get the same version number.
+     */
+    recordDeltaWhenUnlocked(patternId: string, before: object, after: object, metadata?: Record<string, unknown>): Promise<DeltaEvent>;
     /**
      * Create a genesis snapshot for a pattern (version 0).
      * The full object is stored in metadata.snapshot; patches are empty.

package/dist/integrations/ruvector/delta-tracker.js

@@ -8,6 +8,7 @@
  * @module integrations/ruvector/delta-tracker
  */
 import { v4 as uuidv4 } from 'uuid';
+import { writeWhenUnlockedOn } from '../../shared/sqlite-write-queue.js';
 import * as fastJsonPatchNs from 'fast-json-patch';
 // fast-json-patch ships two entry points with different export shapes: its CJS
 // entry (index.js) attaches named exports directly via Object.assign(exports,
@@ -156,6 +157,21 @@ export class DeltaTracker {
     // --------------------------------------------------------------------------
     // Public API
     // --------------------------------------------------------------------------
+    /**
+     * createGenesis() through the shared connection's write queue (#1283). The
+     * version check and the insert run as one queued unit.
+     */
+    createGenesisWhenUnlocked(patternId, snapshot, metadata) {
+        return writeWhenUnlockedOn(this.db, () => this.createGenesis(patternId, snapshot, metadata));
+    }
+    /**
+     * recordDelta() through the shared connection's write queue (#1283). Reading
+     * the current version, the insert and retention run as one queued unit, so
+     * two deltas cannot get the same version number.
+     */
+    recordDeltaWhenUnlocked(patternId, before, after, metadata) {
+        return writeWhenUnlockedOn(this.db, () => this.recordDelta(patternId, before, after, metadata));
+    }
     /**
      * Create a genesis snapshot for a pattern (version 0).
      * The full object is stored in metadata.snapshot; patches are empty.

package/dist/integrations/ruvector/sona-persistence.d.ts

@@ -95,6 +95,8 @@ export declare class PersistentSONAEngine {
     private initPromise;
     private pendingSaves;
     private saveTimer;
+    /** The deferred batch currently being written, if any (#1283). */
+    private flushInFlight;
     private consecutiveSaveFailures;
     private serverClient;
     constructor(config: PersistentSONAConfig);
@@ -419,6 +421,14 @@ export declare class PersistentSONAEngine {
      * Schedule batched save
      */
     private scheduleSave;
+    /**
+     * Write the batched patterns. Each write is queued on the shared connection
+     * (#1283): in the MCP server a locked memory.db no longer freezes the event
+     * loop for the whole busy_timeout per pattern; the write retries
+     * asynchronously instead. A row that still fails stays pending and the batch
+     * is retried with backoff, as before.
+     */
+    private flushPendingSaves;
     /**
      * Update pattern usage in SQLite
      */

package/dist/integrations/ruvector/sona-persistence.js

@@ -29,6 +29,7 @@ import { getUnifiedPersistence } from '../../kernel/unified-persistence.js';
 import { toErrorMessage } from '../../shared/error-utils.js';
 import { safeJsonParse } from '../../shared/safe-json.js';
 import { LoggerFactory } from '../../logging/index.js';
+import { writeWhenUnlockedOn } from '../../shared/sqlite-write-queue.js';
 const logger = LoggerFactory.create('sona-persistence');
 // ============================================================================
 // Schema (added to unified-memory.ts as part of migration)
@@ -112,6 +113,8 @@ export class PersistentSONAEngine {
     initPromise = null;
     pendingSaves = new Map();
     saveTimer = null;
+    /** The deferred batch currently being written, if any (#1283). */
+    flushInFlight = null;
     consecutiveSaveFailures = 0;
     serverClient = null;
     constructor(config) {
@@ -801,6 +804,10 @@ export class PersistentSONAEngine {
      * Close the engine
      */
     async close() {
+        // Let a deferred batch that is already writing finish first (#1283); it
+        // may schedule a retry, which the clearTimeout below then cancels.
+        if (this.flushInFlight)
+            await this.flushInFlight;
         // Flush pending saves
         if (this.saveTimer) {
             clearTimeout(this.saveTimer);
@@ -808,9 +815,9 @@ export class PersistentSONAEngine {
         }
         if (this.pendingSaves.size > 0) {
             const failures = [];
-            for (const pattern of this.pendingSaves.values()) {
+            for (const pattern of Array.from(this.pendingSaves.values())) {
                 try {
-                    this.savePatternToDb(pattern);
+                    await writeWhenUnlockedOn(this.db, () => this.savePatternToDb(pattern));
                     this.pendingSaves.delete(pattern.id);
                 }
                 catch (error) {
@@ -1085,33 +1092,51 @@ export class PersistentSONAEngine {
         }
         this.saveTimer = setTimeout(() => {
             this.saveTimer = null;
-            const patterns = Array.from(this.pendingSaves.values());
-            for (const pattern of patterns) {
-                try {
-                    this.savePatternToDb(pattern);
-                    this.pendingSaves.delete(pattern.id);
-                }
-                catch (error) {
-                    logger.warn('Deferred SONA save failed; retaining pending pattern', {
-                        patternId: pattern.id, error: toErrorMessage(error),
-                    });
-                }
-            }
-            if (this.pendingSaves.size > 0) {
-                this.consecutiveSaveFailures++;
-                // Stop after five failed batches; close() can still flush retained rows.
-                if (this.consecutiveSaveFailures < 5 && this.db?.open) {
-                    this.scheduleSave(Math.min(60000, Math.max(1000, this.config.autoSaveInterval) * 2 ** (this.consecutiveSaveFailures - 1)));
-                }
-            }
-            else {
-                this.consecutiveSaveFailures = 0;
-            }
+            const flush = this.flushPendingSaves().finally(() => {
+                if (this.flushInFlight === flush)
+                    this.flushInFlight = null;
+            });
+            this.flushInFlight = flush;
         }, delayMs);
         // The initial batch must flush on natural exit; only failure retries are optional.
         if (this.consecutiveSaveFailures > 0)
             this.saveTimer.unref();
     }
+    /**
+     * Write the batched patterns. Each write is queued on the shared connection
+     * (#1283): in the MCP server a locked memory.db no longer freezes the event
+     * loop for the whole busy_timeout per pattern; the write retries
+     * asynchronously instead. A row that still fails stays pending and the batch
+     * is retried with backoff, as before.
+     */
+    async flushPendingSaves() {
+        const patterns = Array.from(this.pendingSaves.values());
+        let failed = 0;
+        for (const pattern of patterns) {
+            try {
+                await writeWhenUnlockedOn(this.db, () => this.savePatternToDb(pattern));
+                // A newer snapshot queued during the write stays pending.
+                if (this.pendingSaves.get(pattern.id) === pattern)
+                    this.pendingSaves.delete(pattern.id);
+            }
+            catch (error) {
+                failed++;
+                logger.warn('Deferred SONA save failed; retaining pending pattern', {
+                    patternId: pattern.id, error: toErrorMessage(error),
+                });
+            }
+        }
+        if (failed > 0) {
+            this.consecutiveSaveFailures++;
+            // Stop after five failed batches; close() can still flush retained rows.
+            if (this.consecutiveSaveFailures < 5 && this.db?.open) {
+                this.scheduleSave(Math.min(60000, Math.max(1000, this.config.autoSaveInterval) * 2 ** (this.consecutiveSaveFailures - 1)));
+            }
+        }
+        else {
+            this.consecutiveSaveFailures = 0;
+        }
+    }
     /**
      * Update pattern usage in SQLite
      */

package/dist/kernel/unified-memory.d.ts

@@ -69,6 +69,9 @@ export declare class UnifiedMemoryManager {
     private initialized;
     private vectorsLoaded;
     private initPromise;
+    /** Tail of the FIFO write queue and how many writes are in it (#1263). */
+    private writeQueue;
+    private queuedWrites;
     private preparedStatements;
     private vectorIndex;
     private crdtStore;
@@ -115,6 +118,19 @@ export declare class UnifiedMemoryManager {
      */
     private migrateToV11GoapExecutionSteps;
     private loadVectorIndex;
+    /**
+     * Run a write on the shared connection (#1263). Under the MCP server's lock
+     * wait cap each attempt blocks for at most the cap and the write retries
+     * asynchronously, so a locked memory.db does not freeze the event loop. The
+     * write still fails with SQLITE_BUSY once the configured busyTimeout has
+     * passed. Without a cap (CLI) this is one attempt with the full busyTimeout.
+     *
+     * Writes run one at a time in call order (FIFO), so a later write to the
+     * same key cannot land before an earlier one that is still retrying. A
+     * failed write does not hold up the next. With nothing queued the first
+     * attempt runs synchronously, as the write did before.
+     */
+    writeWhenUnlocked<T>(fn: () => T): Promise<T>;
     kvSet(key: string, value: unknown, namespace?: string, ttl?: number): Promise<void>;
     kvGet<T>(key: string, namespace?: string): Promise<T | undefined>;
     kvDelete(key: string, namespace?: string): Promise<boolean>;
@@ -212,4 +228,12 @@ export declare class UnifiedMemoryManager {
 export declare function getUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): UnifiedMemoryManager;
 export declare function initializeUnifiedMemory(config?: Partial<UnifiedMemoryConfig>): Promise<UnifiedMemoryManager>;
 export declare function resetUnifiedMemory(): void;
+/**
+ * Run a write on `db` through the shared manager's writeWhenUnlocked queue
+ * when `db` is that manager's connection (#1274), for modules that hold only
+ * the raw connection. The write then neither blocks the MCP server's event
+ * loop for the whole busy_timeout nor lands before an earlier queued write.
+ * A write on any other connection runs now, as before.
+ */
+export declare function writeWhenUnlockedOn<T>(db: DatabaseType, fn: () => T): Promise<T>;
 //# sourceMappingURL=unified-memory.d.ts.map

package/dist/kernel/unified-memory.js

@@ -23,6 +23,9 @@
  */
 import { openDatabase as openSafeDatabase } from '../shared/safe-db.js';
 import { safeJsonParse } from '../shared/safe-json.js';
+import { capBusyTimeout } from '../shared/sqlite-lock-wait.js';
+import { registerWriteQueue, unregisterWriteQueue, writeWhenUnlockedOn as queueWriteOn, } from '../shared/sqlite-write-queue.js';
+import { isBusyError, retryWhileBusy, withBusyTimeout } from '../learning/dream/dream-lock-retry.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -121,6 +124,9 @@ export class UnifiedMemoryManager {
     initialized = false;
     vectorsLoaded = false;
     initPromise = null;
+    /** Tail of the FIFO write queue and how many writes are in it (#1263). */
+    writeQueue = Promise.resolve();
+    queuedWrites = 0;
     preparedStatements = new Map();
     // ADR-071 Phase 2C: Always use UnifiedHnswIndex (old implementations decommissioned)
     vectorIndex = new UnifiedHnswIndex('qe-memory');
@@ -307,6 +313,8 @@ export class UnifiedMemoryManager {
             }
             this.vectorsLoaded = false;
             this.initialized = true;
+            // #1283: modules holding only the raw connection queue their writes here.
+            registerWriteQueue(this.db, (fn) => this.writeWhenUnlocked(fn));
             console.log(`[UnifiedMemory] Initialized: ${this.config.dbPath}`);
             this.warnIfDuplicateDatabases();
         }
@@ -558,14 +566,42 @@ export class UnifiedMemoryManager {
     // ============================================================================
     // KV Store Operations (v2 compatible)
     // ============================================================================
+    /**
+     * Run a write on the shared connection (#1263). Under the MCP server's lock
+     * wait cap each attempt blocks for at most the cap and the write retries
+     * asynchronously, so a locked memory.db does not freeze the event loop. The
+     * write still fails with SQLITE_BUSY once the configured busyTimeout has
+     * passed. Without a cap (CLI) this is one attempt with the full busyTimeout.
+     *
+     * Writes run one at a time in call order (FIFO), so a later write to the
+     * same key cannot land before an earlier one that is still retrying. A
+     * failed write does not hold up the next. With nothing queued the first
+     * attempt runs synchronously, as the write did before.
+     */
+    writeWhenUnlocked(fn) {
+        const run = () => retryWhileBusy(this.db, fn, {
+            waitMs: capBusyTimeout(this.config.busyTimeout),
+            budgetMs: this.config.busyTimeout,
+        });
+        // Queued writes yield to the event loop first, so one write's last attempt
+        // and the next one's first never block back to back.
+        const result = this.queuedWrites === 0
+            ? run()
+            : this.writeQueue.then(() => new Promise((r) => setImmediate(r))).then(run);
+        this.queuedWrites++;
+        const settled = result.then(() => undefined, () => undefined);
+        this.writeQueue = settled;
+        void settled.then(() => { this.queuedWrites--; });
+        return result;
+    }
     async kvSet(key, value, namespace = 'default', ttl) {
         this.ensureInitialized();
         const expiresAt = ttl ? Date.now() + ttl * 1000 : null;
         const serialized = JSON.stringify(value);
-        this.db.prepare(`
+        await this.writeWhenUnlocked(() => this.db.prepare(`
       INSERT OR REPLACE INTO kv_store (key, namespace, value, expires_at)
       VALUES (?, ?, ?, ?)
-    `).run(key, namespace, serialized, expiresAt);
+    `).run(key, namespace, serialized, expiresAt));
         // ADR-194: tamper-evident audit (no-op unless the proof-gate is enabled).
         this.auditWrite('kvSet', namespace, key, serialized);
     }
@@ -578,14 +614,22 @@ export class UnifiedMemoryManager {
         if (!row)
             return undefined;
         if (row.expires_at && Date.now() > row.expires_at) {
-            this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace);
+            try {
+                withBusyTimeout(this.db, capBusyTimeout(this.config.busyTimeout), () => this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace));
+            }
+            catch (error) {
+                // #1263: a read must not wait on a locked DB to tidy up; the row stays
+                // expired (filtered here) and kvCleanupExpired removes it later.
+                if (!isBusyError(error))
+                    throw error;
+            }
             return undefined;
         }
         return safeJsonParse(row.value);
     }
     async kvDelete(key, namespace = 'default') {
         this.ensureInitialized();
-        const result = this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace);
+        const result = await this.writeWhenUnlocked(() => this.db.prepare('DELETE FROM kv_store WHERE key = ? AND namespace = ?').run(key, namespace));
         // ADR-194: audit deletes too (no-op unless the proof-gate is enabled).
         if (result.changes > 0)
             this.auditWrite('kvDelete', namespace, key, '');
@@ -613,7 +657,7 @@ export class UnifiedMemoryManager {
     }
     async kvCleanupExpired() {
         this.ensureInitialized();
-        const result = this.db.prepare('DELETE FROM kv_store WHERE expires_at IS NOT NULL AND expires_at < ?').run(Date.now());
+        const result = await this.writeWhenUnlocked(() => this.db.prepare('DELETE FROM kv_store WHERE expires_at IS NOT NULL AND expires_at < ?').run(Date.now()));
         return result.changes;
     }
     // ============================================================================
@@ -716,10 +760,10 @@ export class UnifiedMemoryManager {
         this.ensureInitialized();
         const buffer = this.floatArrayToBuffer(embedding);
         const metadataJson = metadata ? JSON.stringify(metadata) : null;
-        this.db.prepare(`
+        await this.writeWhenUnlocked(() => this.db.prepare(`
       INSERT OR REPLACE INTO vectors (id, namespace, embedding, dimensions, metadata, updated_at)
       VALUES (?, ?, ?, ?, ?, datetime('now'))
-    `).run(id, namespace, buffer, embedding.length, metadataJson);
+    `).run(id, namespace, buffer, embedding.length, metadataJson));
         this.vectorIndex.add(id, embedding);
     }
     async vectorGet(id) {
@@ -736,7 +780,7 @@ export class UnifiedMemoryManager {
     }
     async vectorDelete(id) {
         this.ensureInitialized();
-        const result = this.db.prepare('DELETE FROM vectors WHERE id = ?').run(id);
+        const result = await this.writeWhenUnlocked(() => this.db.prepare('DELETE FROM vectors WHERE id = ?').run(id));
         this.vectorIndex.remove(id);
         return result.changes > 0;
     }
@@ -1037,6 +1081,7 @@ export class UnifiedMemoryManager {
             // hnswlib-node has none of those constraints; multiple instances
             // coexist freely.
             this.vectorIndex.clear();
+            unregisterWriteQueue(this.db);
             this.db.close();
             this.db = null;
             this.initialized = false;
@@ -1076,6 +1121,16 @@ export async function initializeUnifiedMemory(config) {
 export function resetUnifiedMemory() {
     UnifiedMemoryManager.resetInstance();
 }
+/**
+ * Run a write on `db` through the shared manager's writeWhenUnlocked queue
+ * when `db` is that manager's connection (#1274), for modules that hold only
+ * the raw connection. The write then neither blocks the MCP server's event
+ * loop for the whole busy_timeout nor lands before an earlier queued write.
+ * A write on any other connection runs now, as before.
+ */
+export function writeWhenUnlockedOn(db, fn) {
+    return queueWriteOn(db, fn);
+}
 // ============================================================================
 // Process Exit Handlers
 // ============================================================================

package/dist/learning/aqe-learning-engine.js

@@ -155,7 +155,7 @@ export class AQELearningEngine {
                 if (persistence.isInitialized()) {
                     const { PatternNullStore } = await import('./pattern-null-store.js');
                     const nullStore = new PatternNullStore(persistence.getDatabase());
-                    this.experienceCapture.setNullRecorder((record) => nullStore.recordNull(record));
+                    this.experienceCapture.setNullRecorder((record) => nullStore.recordNullWhenUnlocked(record));
                 }
             }
             catch (e) {

package/dist/learning/dream/dream-engine.d.ts

@@ -212,9 +212,10 @@ export declare class DreamEngine {
      * #1060: write the results of a `dream(…, { commit: false })` run, in the
      * same single transaction a normal dream uses. Returns the commit duration
      * in ms. Throws (and writes nothing) if the engine is closed or the write
-     * fails.
+     * fails. #1253: async, because a locked database is retried without
+     * blocking the process.
      */
-    commitDreamResult(result: DreamCycleResult): number;
+    commitDreamResult(result: DreamCycleResult): Promise<number>;
     /**
      * Commit a computed dream, then record it in the witness chain (#1060) and
      * run the default retention steps (#1239).