agentic-qe 3.14.3 → 3.14.4

package/dist/integrations/ruvector/rvf-dual-writer.js

@@ -97,26 +97,42 @@ export class RvfDualWriter {
                 this.rvfAvailable = false;
                 return;
             }
-            // Try open first, create if it fails
-            let nativeAdapter;
-            try {
-                nativeAdapter = adapter.openRvfStore(this.config.rvfPath);
+            const { isRvfLockHeldError, removeStaleRvfLock, quarantineUnusableStore } = await import('./rvf-store-integrity.js');
+            const tryOpen = () => {
+                try {
+                    return { store: adapter.openRvfStore(this.config.rvfPath), error: null };
+                }
+                catch (error) {
+                    return { store: null, error };
+                }
+            };
+            let { store: nativeAdapter, error: openError } = tryOpen();
+            if (!nativeAdapter && isRvfLockHeldError(openError)) {
+                // A dead CLI process can leave a valid RVF behind a native lock. Only
+                // reclaim a lock with a readable dead owner, then retry the open.
+                if (!removeStaleRvfLock(this.config.rvfPath))
+                    throw openError;
+                ({ store: nativeAdapter, error: openError } = tryOpen());
+                if (!nativeAdapter && isRvfLockHeldError(openError))
+                    throw openError;
             }
-            catch {
+            if (!nativeAdapter) {
                 try {
                     nativeAdapter = adapter.createRvfStore(this.config.rvfPath, this.config.dimensions);
                 }
                 catch (createErr) {
-                    // Issue #563: open failed *and* create failed, so the file on disk is
-                    // provably unusable — the signature of an export killed mid-write
-                    // (open → ManifestNotFound, create → FsyncFailed because the path
-                    // exists). Previously this fell to the catch below and disabled RVF
-                    // silently for the whole run. Quarantine and rebuild instead.
-                    const { quarantineUnusableStore } = await import('./rvf-store-integrity.js');
-                    const quarantined = quarantineUnusableStore(this.config.rvfPath, createErr instanceof Error ? createErr.message : String(createErr));
-                    if (!quarantined)
-                        throw createErr; // live peer, or nothing to move
-                    nativeAdapter = adapter.createRvfStore(this.config.rvfPath, this.config.dimensions);
+                    // A peer may have created the file since the first open. Re-open
+                    // before considering recovery, and use that error (not FsyncFailed)
+                    // to distinguish a busy healthy store from structural corruption.
+                    ({ store: nativeAdapter, error: openError } = tryOpen());
+                    if (!nativeAdapter) {
+                        if (isRvfLockHeldError(openError))
+                            throw openError;
+                        const quarantined = quarantineUnusableStore(this.config.rvfPath, createErr instanceof Error ? createErr.message : String(createErr), openError);
+                        if (!quarantined)
+                            throw createErr;
+                        nativeAdapter = adapter.createRvfStore(this.config.rvfPath, this.config.dimensions);
+                    }
                 }
             }
             this.rvfStore = wrapNativeAdapter(nativeAdapter, this.config.dimensions);
@@ -126,6 +142,11 @@ export class RvfDualWriter {
         catch (err) {
             // Native adapter unavailable, or recovery itself failed. Degrade to
             // sqlite-only — but say so, instead of vanishing silently (#563).
+            try {
+                this.rvfStore?.close();
+            }
+            catch { /* best-effort cleanup */ }
+            this.rvfStore = null;
             this.rvfAvailable = false;
             console.warn(`[RVF] Dual-writer disabled for ${this.config.rvfPath}; falling back to SQLite: ` +
                 `${err instanceof Error ? err.message : String(err)}`);

package/dist/integrations/ruvector/rvf-store-integrity.d.ts

@@ -20,9 +20,9 @@
  *     the store magic is `SFVR`; a 104-byte `FLVR` lock is just a live-or-stale
  *     lock record.
  *
- * So the only sound trigger is "open failed *and* create failed": at that point
- * the file is provably unusable. The lock's pid is used as a *guard* — if it is
- * held by a live process, the store is presumed healthy and left alone.
+ * A failed open must be inspected before recovery. `LockHeld` plus a failed
+ * create says nothing about the store's integrity: create refuses to replace
+ * any existing path. Only a structural open failure can justify quarantine.
  */
 /** The pid recorded in `<rvfPath>.lock`, or null if there is no readable lock. */
 export declare function readLockOwnerPid(rvfPath: string): number | null;
@@ -35,15 +35,20 @@ export declare function readLockOwnerPid(rvfPath: string): number | null;
  * "alive", which fails safe — we leave the store alone.
  */
 export declare function isLockHeldByLiveProcess(rvfPath: string): boolean;
+/** The native binding's exclusive-lock failure (never evidence of corruption). */
+export declare function isRvfLockHeldError(err: unknown): boolean;
+/** Only known structural open errors permit replacing a derived cache. */
+export declare function isRvfStructuralError(err: unknown): boolean;
+/** Reclaim a lock only when its record names a process known to have exited. */
+export declare function removeStaleRvfLock(rvfPath: string): boolean;
 /**
  * Move an unusable store and its sidecars aside so the next create succeeds.
  * Returns the quarantine base path, or null if nothing was quarantined.
  *
- * Only call this once open *and* create have both failed — that is the proof
- * the file is unusable. The store is a derived cache, rebuilt from the unified
- * DB, so quarantining is recoverable; we move rather than delete because the
- * bytes may hold writes that never reached SQLite, and they are the only
- * evidence if this recurs.
+ * Call only after a structural open failure and failed create/re-open. The
+ * store is a derived cache, rebuilt from the unified DB; we move rather than
+ * delete because the bytes may hold writes that never reached SQLite and are
+ * the only evidence if this recurs.
  */
-export declare function quarantineUnusableStore(rvfPath: string, reason: string): string | null;
+export declare function quarantineUnusableStore(rvfPath: string, reason: string, openError: unknown): string | null;
 //# sourceMappingURL=rvf-store-integrity.d.ts.map

package/dist/integrations/ruvector/rvf-store-integrity.js

@@ -20,9 +20,9 @@
  *     the store magic is `SFVR`; a 104-byte `FLVR` lock is just a live-or-stale
  *     lock record.
  *
- * So the only sound trigger is "open failed *and* create failed": at that point
- * the file is provably unusable. The lock's pid is used as a *guard* — if it is
- * held by a live process, the store is presumed healthy and left alone.
+ * A failed open must be inspected before recovery. `LockHeld` plus a failed
+ * create says nothing about the store's integrity: create refuses to replace
+ * any existing path. Only a structural open failure can justify quarantine.
  */
 import { existsSync, openSync, readSync, closeSync, renameSync, unlinkSync } from 'fs';
 /** Magic of a lock record (the store's own magic is `SFVR`). */
@@ -90,19 +90,49 @@ export function isLockHeldByLiveProcess(rvfPath) {
     // process still has open. Treat every live owner conservatively.
     return isPidAlive(pid);
 }
+/** The native binding's exclusive-lock failure (never evidence of corruption). */
+export function isRvfLockHeldError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes('LockHeld') || message.includes('0x0300');
+}
+/** Only known structural open errors permit replacing a derived cache. */
+export function isRvfStructuralError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /ManifestNotFound|InvalidMagic|ChecksumMismatch|CorruptStore/i.test(message);
+}
+/** Reclaim a lock only when its record names a process known to have exited. */
+export function removeStaleRvfLock(rvfPath) {
+    const pid = readLockOwnerPid(rvfPath);
+    if (pid === null || isPidAlive(pid))
+        return false;
+    try {
+        // A concurrent owner could have replaced the record since the first read.
+        if (readLockOwnerPid(rvfPath) !== pid)
+            return false;
+        unlinkSync(`${rvfPath}.lock`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Move an unusable store and its sidecars aside so the next create succeeds.
  * Returns the quarantine base path, or null if nothing was quarantined.
  *
- * Only call this once open *and* create have both failed — that is the proof
- * the file is unusable. The store is a derived cache, rebuilt from the unified
- * DB, so quarantining is recoverable; we move rather than delete because the
- * bytes may hold writes that never reached SQLite, and they are the only
- * evidence if this recurs.
+ * Call only after a structural open failure and failed create/re-open. The
+ * store is a derived cache, rebuilt from the unified DB; we move rather than
+ * delete because the bytes may hold writes that never reached SQLite and are
+ * the only evidence if this recurs.
  */
-export function quarantineUnusableStore(rvfPath, reason) {
+export function quarantineUnusableStore(rvfPath, reason, openError) {
     if (!existsSync(rvfPath))
         return null;
+    // Native create reports FsyncFailed for *every* existing path, including a
+    // healthy one. A last observed LockHeld, permission, or I/O error must never
+    // trigger quarantine even when the owner exits before this check.
+    if (!isRvfStructuralError(openError))
+        return null;
     // Never pull a store out from under a live peer.
     if (isLockHeldByLiveProcess(rvfPath)) {
         console.warn(`[RVF] ${rvfPath} is unusable but its lock is held by a live process — ` +

package/dist/integrations/ruvector/shared-rvf-adapter.js

@@ -15,7 +15,7 @@
 import { findProjectRoot } from '../../kernel/project-root.js';
 // Issue #563: static import — this module is fs-only, and a require() here
 // would not resolve under the test runner.
-import { quarantineUnusableStore, isLockHeldByLiveProcess, readLockOwnerPid, } from './rvf-store-integrity.js';
+import { quarantineUnusableStore, isLockHeldByLiveProcess, isRvfLockHeldError, removeStaleRvfLock, readLockOwnerPid, } from './rvf-store-integrity.js';
 let sharedAdapter = null;
 let initAttempted = false;
 // ---------------------------------------------------------------------------
@@ -122,10 +122,6 @@ function openOrCreateRvf(openFn, createFn, rvfPath, dimensions) {
             return { adapter: null, err };
         }
     };
-    const isLockHeld = (err) => {
-        const m = err instanceof Error ? err.message : String(err);
-        return m.includes('LockHeld') || m.includes('0x0300');
-    };
     // Pass 1: try to open whatever's there.
     let { adapter: opened, err: openErr } = tryOpen();
     // Pass 1.5: stale-lock recovery. The native binding writes a `<rvfPath>.lock`
@@ -141,7 +137,7 @@ function openOrCreateRvf(openFn, createFn, rvfPath, dimensions) {
     // assumption. This includes a lock owned by the current PID: another
     // in-process adapter may still hold the store, so PID equality is not proof
     // that the lock can be removed safely.
-    if (!opened && isLockHeld(openErr)) {
+    if (!opened && isRvfLockHeldError(openErr)) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             const fs = require('fs');
@@ -150,8 +146,7 @@ function openOrCreateRvf(openFn, createFn, rvfPath, dimensions) {
                 console.warn(`[RVF] ${rvfPath} is locked by a live process (pid ${readLockOwnerPid(rvfPath)}) — ` +
                     'not breaking the lock; degrading to SQLite for this run.');
             }
-            else if (fs.existsSync(lockPath)) {
-                fs.unlinkSync(lockPath);
+            else if (removeStaleRvfLock(rvfPath)) {
                 console.warn(`[RVF] Removed stale lock file at ${lockPath} (prior process exited without closing). ` +
                     'Retrying open. If you see this repeatedly under live concurrency, file an issue.');
                 ({ adapter: opened, err: openErr } = tryOpen());
@@ -185,29 +180,31 @@ function openOrCreateRvf(openFn, createFn, rvfPath, dimensions) {
     catch (createErr) {
         // Pass 3: create failed (likely FsyncFailed because a peer process won
         // the race). Try open one more time.
+        let reopened;
         try {
-            const reopened = openFn(rvfPath);
-            if (reopened.dimension() !== dimensions) {
-                try {
-                    reopened.close();
-                }
-                catch { /* best-effort */ }
-                throw new Error(`RVF dimension mismatch after race (file=${reopened.dimension()}, requested=${dimensions})`);
-            }
-            return reopened;
+            reopened = openFn(rvfPath);
         }
-        catch {
-            // Pass 4 (#563): open failed, create failed, re-open failed. The file is
-            // provably unusable — the signature of an export killed mid-write, which
-            // used to disable the RVF backend permanently. Quarantine it (unless a
-            // live process holds its lock) and rebuild the derived cache.
-            const quarantined = quarantineUnusableStore(rvfPath, createErr instanceof Error ? createErr.message : String(createErr));
+        catch (reopenErr) {
+            // A failed create only proves that a path exists. The final open error
+            // must be structural before we move any store aside.
+            if (isRvfLockHeldError(reopenErr))
+                throw reopenErr;
+            const quarantined = quarantineUnusableStore(rvfPath, createErr instanceof Error ? createErr.message : String(createErr), reopenErr);
             if (quarantined) {
                 return createFn(rvfPath, dimensions);
             }
             // Fall through with the more informative original error.
             throw createErr instanceof Error ? createErr : new Error(String(createErr));
         }
+        const actualDim = reopened.dimension();
+        if (actualDim !== dimensions) {
+            try {
+                reopened.close();
+            }
+            catch { /* best-effort */ }
+            throw new Error(`RVF dimension mismatch after race (file=${actualDim}, requested=${dimensions})`);
+        }
+        return reopened;
     }
 }
 /**

package/dist/kernel/memory-factory.js

@@ -5,6 +5,8 @@
  * NOTE: All backends now delegate to UnifiedMemoryManager for true unified storage.
  * The 'agentdb' type is kept for backward compatibility but maps to HybridMemoryBackend.
  */
+import { existsSync, statSync } from 'node:fs';
+import { extname, join } from 'node:path';
 import { InMemoryBackend } from './memory-backend.js';
 import { HybridMemoryBackend } from './hybrid-backend.js';
 import { MEMORY_CONSTANTS, DATABASE_POOL_CONSTANTS } from './constants.js';
@@ -95,21 +97,29 @@ export async function createMemoryBackend(config, autoInitialize = true) {
  */
 export async function createDefaultMemoryBackend(autoInitialize = true) {
     const backendType = process.env.AQE_MEMORY_BACKEND ?? 'memory';
-    const storagePath = process.env.AQE_MEMORY_PATH ?? '.agentic-qe';
+    const storagePath = process.env.AQE_MEMORY_PATH;
+    // Settings installers supply a database filename. Preserve legacy directory
+    // overrides, but never append memory.db to an existing file or a DB filename.
+    const databasePath = !storagePath ? DEFAULT_MEMORY_DB_PATH
+        : storagePath === ':memory:' ? storagePath
+            : existsSync(storagePath)
+                ? (statSync(storagePath).isDirectory() ? join(storagePath, 'memory.db') : storagePath)
+                : /\.(db|sqlite|sqlite3)$/i.test(extname(storagePath))
+                    ? storagePath : join(storagePath, 'memory.db');
     const config = {
         type: backendType,
         sqlite: {
-            path: `${storagePath}/memory.db`,
+            path: databasePath,
             walMode: true,
         },
         agentdb: {
             // Now just uses unified memory.db
-            path: `${storagePath}/memory.db`,
+            path: databasePath,
         },
         hybrid: {
             enableFallback: true,
             sqlite: {
-                path: `${storagePath}/memory.db`,
+                path: databasePath,
             },
         },
     };

package/dist/kernel/project-root.js

@@ -15,12 +15,14 @@ import * as fs from 'fs';
 import * as path from 'path';
 /** Module-level cache for findProjectRoot result. */
 let _cachedProjectRoot = null;
+let _cachedStartDir = null;
 /**
  * Clear the cached project root. Useful for testing or when the
  * environment changes at runtime.
  */
 export function clearProjectRootCache() {
     _cachedProjectRoot = null;
+    _cachedStartDir = null;
 }
 /**
  * Find the project root by walking up the directory tree.
@@ -36,14 +38,14 @@ export function clearProjectRootCache() {
  * and the result is cached at module level for subsequent calls.
  */
 export function findProjectRoot(startDir = process.cwd()) {
-    if (_cachedProjectRoot) {
+    // Environment overrides may change between SDK calls. Do not let a cached
+    // discovery hide a new explicit root or leak it after the override is unset.
+    if (process.env.AQE_PROJECT_ROOT)
+        return process.env.AQE_PROJECT_ROOT;
+    const dir = path.resolve(startDir);
+    if (_cachedProjectRoot && _cachedStartDir === dir)
         return _cachedProjectRoot;
-    }
-    if (process.env.AQE_PROJECT_ROOT) {
-        _cachedProjectRoot = process.env.AQE_PROJECT_ROOT;
-        return _cachedProjectRoot;
-    }
-    const dir = startDir;
+    _cachedStartDir = dir;
     const root = path.parse(dir).root;
     let checkDir = dir;
     let nearestAqeDir = null;
@@ -79,7 +81,7 @@ export function findProjectRoot(startDir = process.cwd()) {
         _cachedProjectRoot = topmostPackageJson;
     }
     else {
-        _cachedProjectRoot = process.cwd();
+        _cachedProjectRoot = dir;
     }
     return _cachedProjectRoot;
 }

package/dist/kernel/unified-memory.js

@@ -141,7 +141,7 @@ export class UnifiedMemoryManager {
             this.config.dbPath = ':memory:';
             return;
         }
-        if (!path.isAbsolute(this.config.dbPath)) {
+        if (this.config.dbPath !== ':memory:' && !path.isAbsolute(this.config.dbPath)) {
             const projectRoot = findProjectRoot();
             this.config.dbPath = path.join(projectRoot, this.config.dbPath);
         }

package/dist/learning/local-judge-client.d.ts

@@ -9,12 +9,13 @@
  *
  * Env vars (all optional — client is disabled if none set):
  *   NAGUAL_JUDGE_URL    — base URL of Ollama server (default: http://localhost:11434)
- *   NAGUAL_JUDGE_MODEL  — model to use (default: qwen3:8b)
+ *   NAGUAL_JUDGE_MODEL  — model to use (default: qwen3-coder:30b)
  *
- * Supported models (in preference order for M-series Macs):
- *   gemma4:12b-mlx  — 10GB, MLX-optimised, best quality on Apple Silicon
- *   qwen3:8b        — 5.2GB, strong reasoning, already installed
- *   qwen3:30b-a3b   — 18GB, highest quality, use only if RAM permits
+ * Supported models:
+ *   qwen3-coder:30b — ~18GB MoE, project default (ADR-111), fast and reliable
+ *   qwen3:30b-a3b   — ~18GB, same quality class, slower (spends time "thinking")
+ *   gemma4:12b-mlx  — 10GB, MLX-optimised alternative on Apple Silicon
+ *   qwen3:8b        — 5.2GB, low-RAM fallback only; below the ADR-111 quality floor
  */
 /** Output of a judge evaluation. */
 export interface JudgeResult {

package/dist/learning/local-judge-client.js

@@ -9,18 +9,19 @@
  *
  * Env vars (all optional — client is disabled if none set):
  *   NAGUAL_JUDGE_URL    — base URL of Ollama server (default: http://localhost:11434)
- *   NAGUAL_JUDGE_MODEL  — model to use (default: qwen3:8b)
+ *   NAGUAL_JUDGE_MODEL  — model to use (default: qwen3-coder:30b)
  *
- * Supported models (in preference order for M-series Macs):
- *   gemma4:12b-mlx  — 10GB, MLX-optimised, best quality on Apple Silicon
- *   qwen3:8b        — 5.2GB, strong reasoning, already installed
- *   qwen3:30b-a3b   — 18GB, highest quality, use only if RAM permits
+ * Supported models:
+ *   qwen3-coder:30b — ~18GB MoE, project default (ADR-111), fast and reliable
+ *   qwen3:30b-a3b   — ~18GB, same quality class, slower (spends time "thinking")
+ *   gemma4:12b-mlx  — 10GB, MLX-optimised alternative on Apple Silicon
+ *   qwen3:8b        — 5.2GB, low-RAM fallback only; below the ADR-111 quality floor
  */
 import { LoggerFactory } from '../logging/index.js';
 import { resolveOllamaBaseUrl } from '../shared/llm/ollama-url.js';
 const logger = LoggerFactory.create('local-judge');
 const DEFAULT_URL = 'http://localhost:11434';
-const DEFAULT_MODEL = 'qwen3:8b';
+const DEFAULT_MODEL = 'qwen3-coder:30b';
 const JUDGE_TIMEOUT_MS = 30_000;
 const MAX_TEXT_LENGTH = 600;
 // Thinking models (gemma4, qwen3) need extra tokens to finish reasoning before output

package/dist/learning/pattern-store.js

@@ -18,7 +18,7 @@ import { createRvfStore as _createRvfStore, openRvfStore as _openRvfStore, isRvf
 // esbuild bundle but throws under the test runner, which silently changed which
 // code path tests exercised. Neither module loads the native binding at import
 // time, so this costs nothing at startup.
-import { quarantineUnusableStore } from '../integrations/ruvector/rvf-store-integrity.js';
+import { isRvfLockHeldError, quarantineUnusableStore, removeStaleRvfLock, } from '../integrations/ruvector/rvf-store-integrity.js';
 import { getSharedRvfAdapter } from '../integrations/ruvector/shared-rvf-adapter.js';
 import { toErrorMessage, toError } from '../shared/error-utils.js';
 import { calculateQualityScore, shouldPromotePattern, validateQEPattern, mapQEDomainToAQE, PROMOTION_THRESHOLD, } from './qe-patterns.js';
@@ -1498,22 +1498,32 @@ export function createPatternStore(memory, config) {
                         // esbuild bundle but throws "Cannot find module" under the test
                         // runner, so this ladder — including its corruption recovery —
                         // was unreachable from any test.
+                        let openError;
                         const tryOpen = () => {
                             try {
                                 return _openRvfStore(path);
                             }
-                            catch {
+                            catch (err) {
+                                openError = err;
                                 return null;
                             }
                         };
                         let adapter = tryOpen();
+                        if (!adapter && isRvfLockHeldError(openError)) {
+                            if (!removeStaleRvfLock(path))
+                                throw openError;
+                            adapter = tryOpen();
+                            if (!adapter && isRvfLockHeldError(openError))
+                                throw openError;
+                        }
                         if (adapter) {
-                            if (adapter.dimension() !== dim) {
+                            const actualDim = adapter.dimension();
+                            if (actualDim !== dim) {
                                 try {
                                     adapter.close();
                                 }
                                 catch { /* best-effort */ }
-                                throw new Error(`RVF dimension mismatch (file=${adapter.dimension()}, requested=${dim})`);
+                                throw new Error(`RVF dimension mismatch (file=${actualDim}, requested=${dim})`);
                             }
                             return adapter;
                         }
@@ -1522,14 +1532,22 @@ export function createPatternStore(memory, config) {
                         }
                         catch (createErr) {
                             adapter = tryOpen();
-                            if (adapter && adapter.dimension() === dim)
+                            if (adapter) {
+                                if (adapter.dimension() !== dim) {
+                                    const actualDim = adapter.dimension();
+                                    try {
+                                        adapter.close();
+                                    }
+                                    catch { /* best-effort */ }
+                                    throw new Error(`RVF dimension mismatch (file=${actualDim}, requested=${dim})`);
+                                }
                                 return adapter;
-                            // Issue #563: open failed, create failed, re-open failed — the
-                            // store is provably unusable (an export killed mid-write leaves
-                            // exactly this). Without recovery, RvfPatternStore.initialize()
-                            // logs "vector search is DISABLED" and stays that way for the
-                            // life of the process.
-                            if (quarantineUnusableStore(path, createErr instanceof Error ? createErr.message : String(createErr))) {
+                            }
+                            if (isRvfLockHeldError(openError))
+                                throw openError;
+                            // Only a structural open failure can justify quarantining a
+                            // store that create() also refused to replace (#563, #574).
+                            if (quarantineUnusableStore(path, createErr instanceof Error ? createErr.message : String(createErr), openError)) {
                                 return _createRvfStore(path, dim);
                             }
                             throw createErr;