agentic-qe 3.14.3 → 3.14.5

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.d.ts

@@ -21,7 +21,7 @@ export declare function clearProjectRootCache(): void;
  *
  * Priority order:
  * 1. AQE_PROJECT_ROOT environment variable (set by MCP config or init)
- * 2. Walk up looking for the NEAREST .agentic-qe directory (existing AQE project)
+ * 2. Nearest .agentic-qe at or below the nearest .git boundary
  * 3. Walk up looking for .git directory (git repo root)
  * 4. Walk up looking for package.json WITHOUT node_modules sibling (monorepo root)
  * 5. Fallback to current working directory

package/dist/kernel/project-root.js

@@ -12,22 +12,30 @@
  * @module kernel/project-root
  */
 import * as fs from 'fs';
+import * as os from 'os';
 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;
+}
+/** True when `dir` is `parent` or inside it. */
+function isWithin(dir, parent) {
+    const rel = path.relative(parent, dir);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
 }
 /**
  * Find the project root by walking up the directory tree.
  *
  * Priority order:
  * 1. AQE_PROJECT_ROOT environment variable (set by MCP config or init)
- * 2. Walk up looking for the NEAREST .agentic-qe directory (existing AQE project)
+ * 2. Nearest .agentic-qe at or below the nearest .git boundary
  * 3. Walk up looking for .git directory (git repo root)
  * 4. Walk up looking for package.json WITHOUT node_modules sibling (monorepo root)
  * 5. Fallback to current working directory
@@ -36,15 +44,26 @@ 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;
+    _cachedStartDir = dir;
+    const root = path.parse(dir).root;
+    // A store directly in $HOME is almost always a stray from an `aqe` run in
+    // the home directory. Outside any git repository there is no boundary to
+    // stop at, so never let it claim a descendant directory (#735/#516); an
+    // `aqe` run from $HOME itself still uses it, and AQE_PROJECT_ROOT overrides.
+    let home = null;
+    try {
+        home = path.resolve(os.homedir());
     }
-    if (process.env.AQE_PROJECT_ROOT) {
-        _cachedProjectRoot = process.env.AQE_PROJECT_ROOT;
-        return _cachedProjectRoot;
+    catch {
+        home = null;
     }
-    const dir = startDir;
-    const root = path.parse(dir).root;
     let checkDir = dir;
     let nearestAqeDir = null;
     let lowestGitDir = null;
@@ -53,8 +72,12 @@ export function findProjectRoot(startDir = process.cwd()) {
         // Issue #516: prefer the NEAREST (lowest) .agentic-qe, mirroring the
         // .git logic below. Keeping the topmost match let an ancestor store
         // (e.g. ~/.agentic-qe, created by any `aqe` run from $HOME) hijack
-        // every descendant project and fragment its learning into $HOME.
-        if (fs.existsSync(path.join(checkDir, '.agentic-qe'))) {
+        // every descendant project and fragment its learning into $HOME. Stop
+        // considering stores above the nearest git boundary, even when the repo
+        // has not been initialized with AQE yet.
+        const isHomeStoreAboveStart = checkDir === home && checkDir !== dir
+            && !isWithin(dir, path.join(checkDir, '.agentic-qe'));
+        if (lowestGitDir === null && !isHomeStoreAboveStart && fs.existsSync(path.join(checkDir, '.agentic-qe'))) {
             if (nearestAqeDir === null) {
                 nearestAqeDir = checkDir;
             }
@@ -79,7 +102,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/embedder-identity-store.js

@@ -13,9 +13,10 @@
  * We never throw out of these helpers under expected conditions; failure
  * reasons are surfaced as thrown errors only for genuine I/O problems.
  */
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { findProjectRoot } from '../kernel/project-root.js';
 // `require` is unavailable in pure ESM; createRequire gives us synchronous
 // access to CommonJS modules like better-sqlite3 from the ESM build output.
 const nodeRequire = createRequire(import.meta.url);
@@ -26,8 +27,8 @@ const nodeRequire = createRequire(import.meta.url);
 function getMemoryDbPath() {
     const env = process.env.AQE_MEMORY_PATH;
     if (env && env.length > 0)
-        return env;
-    return join(process.cwd(), '.agentic-qe', 'memory.db');
+        return env === ':memory:' ? env : resolve(findProjectRoot(), env);
+    return join(findProjectRoot(), '.agentic-qe', 'memory.db');
 }
 const NAMESPACE = '_system';
 const KEY_PREFIX = 'embedder_identity:';

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';
@@ -30,7 +30,7 @@ import { createVectorDeltaTracker, } from '../integrations/ruvector/vector-delta
 import { createHopfieldMemory } from '../integrations/ruvector/hopfield-memory.js';
 import { createHyperbolicPatternIndex, } from './hyperbolic-pattern-index.js';
 import { PatternNullStore } from './pattern-null-store.js';
-import { getActiveEmbeddingSpaceIdentity } from './real-embeddings.js';
+import { ensureEndpointEmbeddingSpaceIdentity, getActiveEmbeddingSpaceIdentity } from './real-embeddings.js';
 import { PatternMutationError } from './pattern-mutation-error.js';
 // ============================================================================
 // R1: HDC Fingerprint Singleton (lazy-initialized)
@@ -244,6 +244,10 @@ export class PatternStore {
      */
     async initializeHNSWInternal() {
         try {
+            // #754: resolve a configured endpoint's identity before binding HNSW.
+            if (!getActiveEmbeddingSpaceIdentity() && !this.config.embeddingSpaceId) {
+                await ensureEndpointEmbeddingSpaceIdentity();
+            }
             this.hnswSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId ?? null;
             if (!this.hnswSpaceId) {
                 throw new Error('VECTOR_SPACE_UNVERIFIED: cannot initialize HNSW without runtime provenance');
@@ -1498,22 +1502,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 +1536,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;

package/dist/learning/real-embeddings.d.ts

@@ -86,4 +86,12 @@ export declare function isUsingEndpoint(): boolean;
 export declare function getEndpointIdentity(): EndpointIdentity | null;
 /** Runtime-backed identity of the initialized embedding space. */
 export declare function getActiveEmbeddingSpaceIdentity(): EmbeddingSpaceIdentity | null;
+/**
+ * #754: resolve the configured endpoint's embedding-space identity before an
+ * index binder (RVF pattern store, brain.rvf dual writer, SQLite HNSW) checks
+ * its space manifest. The endpoint runtime otherwise initializes lazily on the
+ * first embed call — after the binder has already refused for the process.
+ * Returns null when no endpoint is configured, so binders stay fail-closed.
+ */
+export declare function ensureEndpointEmbeddingSpaceIdentity(): Promise<EmbeddingSpaceIdentity | null>;
 //# sourceMappingURL=real-embeddings.d.ts.map

package/dist/learning/real-embeddings.js

@@ -410,4 +410,20 @@ export function getEndpointIdentity() {
 export function getActiveEmbeddingSpaceIdentity() {
     return activeEmbeddingSpaceIdentity;
 }
+/**
+ * #754: resolve the configured endpoint's embedding-space identity before an
+ * index binder (RVF pattern store, brain.rvf dual writer, SQLite HNSW) checks
+ * its space manifest. The endpoint runtime otherwise initializes lazily on the
+ * first embed call — after the binder has already refused for the process.
+ * Returns null when no endpoint is configured, so binders stay fail-closed.
+ */
+export async function ensureEndpointEmbeddingSpaceIdentity() {
+    if (activeEmbeddingSpaceIdentity)
+        return activeEmbeddingSpaceIdentity;
+    const endpoint = process.env.AQE_EMBEDDER_ENDPOINT;
+    if (!endpoint)
+        return null;
+    await initializeModel({ endpoint, endpointToken: process.env.AQE_EMBEDDER_TOKEN });
+    return activeEmbeddingSpaceIdentity;
+}
 //# sourceMappingURL=real-embeddings.js.map

package/dist/learning/rvf-pattern-store.js

@@ -16,7 +16,7 @@ import { ok, err } from '../shared/types/index.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { calculateQualityScore, validateQEPattern, mapQEDomainToAQE, PROMOTION_THRESHOLD, } from './qe-patterns.js';
 import { DEFAULT_PATTERN_STORE_CONFIG } from './pattern-store.js';
-import { getActiveEmbeddingSpaceIdentity } from './real-embeddings.js';
+import { ensureEndpointEmbeddingSpaceIdentity, getActiveEmbeddingSpaceIdentity } from './real-embeddings.js';
 import { verifyOrCreateEmbeddingSpaceManifest } from './embedding-space.js';
 import { PatternMutationError } from './pattern-mutation-error.js';
 // ============================================================================
@@ -75,6 +75,12 @@ export class RvfPatternStore {
             return;
         }
         try {
+            // The endpoint runtime is lazy. Resolve its executable identity before
+            // binding a new RVF index; otherwise every fresh process sees null here
+            // and permanently disables RVF even though the endpoint is configured.
+            if (!this.embeddingSpaceId && !getActiveEmbeddingSpaceIdentity()) {
+                await ensureEndpointEmbeddingSpaceIdentity();
+            }
             this.adapter = this.createAdapter(this.rvfPath, this.config.embeddingDimension);
             const activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.embeddingSpaceId ?? null;
             verifyOrCreateEmbeddingSpaceManifest(this.rvfPath, activeSpaceId, this.adapter.status()?.totalVectors ?? 0);
@@ -90,9 +96,10 @@ export class RvfPatternStore {
                 this.adapter?.close();
             }
             catch { /* best effort */ }
-            console.error(`[RvfPatternStore] ERROR: RVF native init failed — vector search is DISABLED. ` +
+            console.error(`[RvfPatternStore] ERROR: RVF initialization failed — vector search is DISABLED. ` +
                 `Cause: ${this.rvfInitError}. ` +
-                `Fix: install @ruvector/rvf-node native bindings, or set useRVFPatternStore=false to use SQLite HNSW.`);
+                `Fix: check the embedder endpoint and @ruvector/rvf-node binding, ` +
+                `or set RUVECTOR_USE_RVF_PATTERN_STORE=false to use SQLite HNSW.`);
             this.adapter = null;
             this.initialized = true; // mark initialized to prevent retry loops
         }