agentic-qe 3.14.4 → 3.14.6

package/dist/init/token-bootstrap.js

@@ -12,10 +12,11 @@ import * as fs from 'fs';
 import { initializeTokenOptimizer, TokenOptimizerService } from '../optimization/token-optimizer-service.js';
 import { TokenMetricsCollector } from '../learning/token-tracker.js';
 import { createDefaultMemoryBackend } from '../kernel/memory-factory.js';
+import { findProjectRoot } from '../kernel/project-root.js';
 const DEFAULT_CONFIG = {
     enableOptimization: true,
     enablePersistence: true,
-    storagePath: process.env.AQE_STORAGE_PATH ?? '.agentic-qe',
+    storagePath: '.agentic-qe',
     autoSaveIntervalMs: 60000,
     verbose: process.env.AQE_VERBOSE === 'true',
 };
@@ -36,7 +37,16 @@ export async function bootstrapTokenTracking(config) {
     if (initialized) {
         return;
     }
-    const cfg = { ...DEFAULT_CONFIG, ...config };
+    // Resolve the project before creating any directory: a new cwd-local store
+    // would otherwise become the nearest AQE root and split project memory.
+    // A relative AQE_STORAGE_PATH is anchored at the project root too, so it
+    // cannot recreate a cwd-local store from a subdirectory.
+    const envStorage = process.env.AQE_STORAGE_PATH;
+    const cfg = {
+        ...DEFAULT_CONFIG, ...config,
+        storagePath: config?.storagePath
+            ?? (envStorage ? path.resolve(findProjectRoot(), envStorage) : path.join(findProjectRoot(), '.agentic-qe')),
+    };
     if (cfg.verbose) {
         console.log('[TokenBootstrap] Initializing token tracking...');
     }

package/dist/init/types.d.ts

@@ -227,6 +227,16 @@ export interface InitResult {
             policy: 'full' | 'compact' | 'none';
             ownedBytes: number;
         };
+        codexComponents?: {
+            hooks: {
+                status: string;
+                error?: string;
+            };
+            skills: {
+                status: string;
+                error?: string;
+            };
+        };
     };
     totalDurationMs: number;
     timestamp: Date;
@@ -304,6 +314,12 @@ export declare const DEFAULT_HOOKS_CONFIG: HooksConfig;
 export declare const DEFAULT_SKILLS_CONFIG: SkillsConfig;
 export declare const DEFAULT_AUTO_TUNING_CONFIG: AutoTuningConfig;
 export declare const DEFAULT_N8N_PLATFORM_CONFIG: N8nPlatformConfig;
+/**
+ * The QE domains `aqe init` enables by default: every loadable DDD domain
+ * plugin, i.e. the canonical shared ALL_DOMAINS minus the cross-domain
+ * `coordination` context (the Queen, not a domain plugin). Derived — never
+ * hand-maintained — so fresh and existing installs cannot drift (#778).
+ */
 export declare const ALL_DOMAINS: string[];
 /**
  * Get the current AQE version from build-time constant

package/dist/init/types.js

@@ -4,6 +4,8 @@
  *
  * Types for project analysis, self-configuration, and initialization.
  */
+import { ALL_DOMAINS as CANONICAL_DOMAINS } from '../shared/types/index.js';
+import { PROMOTION_MIN_SUCCESS_RATE, PROMOTION_THRESHOLD, } from '../learning/qe-patterns.js';
 // ============================================================================
 // Default Configurations
 // ============================================================================
@@ -16,8 +18,9 @@ export const DEFAULT_LEARNING_CONFIG = {
     enabled: true,
     pretrainedPatterns: true,
     hnswConfig: DEFAULT_HNSW_CONFIG,
-    promotionThreshold: 3,
-    qualityThreshold: 0.7,
+    // Single source of truth: the values the learning runtime enforces (#778).
+    promotionThreshold: PROMOTION_THRESHOLD,
+    qualityThreshold: PROMOTION_MIN_SUCCESS_RATE,
     embeddingModel: 'auto',
 };
 export const DEFAULT_ROUTING_CONFIG = {
@@ -71,21 +74,13 @@ export const DEFAULT_N8N_PLATFORM_CONFIG = {
     installSkills: true,
     installTypeScriptAgents: false,
 };
-export const ALL_DOMAINS = [
-    'test-generation',
-    'test-execution',
-    'coverage-analysis',
-    'quality-assessment',
-    'defect-intelligence',
-    'requirements-validation',
-    'code-intelligence',
-    'security-compliance',
-    'contract-testing',
-    'visual-accessibility',
-    'chaos-resilience',
-    'learning-optimization',
-    'enterprise-integration',
-];
+/**
+ * The QE domains `aqe init` enables by default: every loadable DDD domain
+ * plugin, i.e. the canonical shared ALL_DOMAINS minus the cross-domain
+ * `coordination` context (the Queen, not a domain plugin). Derived — never
+ * hand-maintained — so fresh and existing installs cannot drift (#778).
+ */
+export const ALL_DOMAINS = CANONICAL_DOMAINS.filter((d) => d !== 'coordination');
 /**
  * Get the current AQE version from build-time constant
  */
@@ -103,14 +98,15 @@ export function createDefaultConfig(projectName, projectRoot) {
             root: projectRoot,
             type: 'single',
         },
-        learning: DEFAULT_LEARNING_CONFIG,
-        routing: DEFAULT_ROUTING_CONFIG,
-        workers: DEFAULT_WORKERS_CONFIG,
-        hooks: DEFAULT_HOOKS_CONFIG,
-        skills: DEFAULT_SKILLS_CONFIG,
-        autoTuning: DEFAULT_AUTO_TUNING_CONFIG,
+        // Cloned so callers that mutate the config cannot corrupt the shared defaults.
+        learning: structuredClone(DEFAULT_LEARNING_CONFIG),
+        routing: structuredClone(DEFAULT_ROUTING_CONFIG),
+        workers: structuredClone(DEFAULT_WORKERS_CONFIG),
+        hooks: structuredClone(DEFAULT_HOOKS_CONFIG),
+        skills: structuredClone(DEFAULT_SKILLS_CONFIG),
+        autoTuning: structuredClone(DEFAULT_AUTO_TUNING_CONFIG),
         domains: {
-            enabled: ALL_DOMAINS,
+            enabled: [...ALL_DOMAINS],
             disabled: [],
         },
         agents: {

package/dist/integrations/coherence/coherence-service.js

@@ -31,6 +31,31 @@
 import { DEFAULT_COHERENCE_CONFIG, DEFAULT_COHERENCE_LOGGER, WasmNotLoadedError, CoherenceError, } from './types.js';
 import { toErrorMessage, toError } from '../../shared/error-utils.js';
 import { CohomologyAdapter, SpectralAdapter, CausalAdapter, CategoryAdapter, HomotopyAdapter, WitnessAdapter, } from './engines/index.js';
+import { tallyVotes, describeLeader, describeBreakdown } from './vote-tally.js';
+/** Fallback consensus is valid only when more than this share of votes agree */
+const FALLBACK_MAJORITY_THRESHOLD = 0.6;
+/**
+ * Minimum number of voters for unanimity to be flagged as possible false
+ * consensus. Two agreeing agents are too few to call it groupthink.
+ */
+const MIN_VOTERS_FOR_FALSE_CONSENSUS = 3;
+/**
+ * False consensus means votes that *appear* unified but may not be
+ * (tool contract: "appears unified but isn't"). From verdicts alone the only
+ * observable "appears unified" signal is unanimity, so both the spectral and
+ * the fallback path flag unanimity among at least three voters as a risk.
+ * A split vote (e.g. 2 pass / 1 fail) shows its disagreement openly: it is a
+ * majority or an unverified consensus, never a false one (issue #535).
+ */
+function appearsFalselyUnified(tally) {
+    return tally.isUnanimous && tally.total >= MIN_VOTERS_FOR_FALSE_CONSENSUS;
+}
+/** e.g. "3 of 3 votes 'pass'" or "2 of 3 votes 'pass'; 2 'pass' / 1 'fail'" */
+function describeTally(tally) {
+    return tally.isUnanimous
+        ? describeLeader(tally)
+        : `${describeLeader(tally)}; ${describeBreakdown(tally)}`;
+}
 // ============================================================================
 // Coherence Service Implementation
 // ============================================================================
@@ -557,15 +582,44 @@ export class CoherenceService {
                 }
                 const collapseRisk = this.spectralAdapter.predictCollapseRisk();
                 const fiedlerValue = this.spectralAdapter.computeFiedlerValue();
+                const tally = tallyVotes(votes);
+                // When every vote agrees and carries positive confidence, the agreement
+                // graph is complete with positive edge weights, so its algebraic
+                // connectivity is necessarily > 0. A non-positive value here means the
+                // engine's eigen-solver result cannot be trusted; count votes instead
+                // of reporting a unanimous vote as a collapsed one.
+                if (tally.isUnanimous && votes.every(v => v.confidence > 0) && !(fiedlerValue > 0)) {
+                    this.logger.warn('Spectral engine returned a zero Fiedler value for a connected agreement graph, using fallback', {
+                        fiedlerValue,
+                        voteCount: votes.length,
+                    });
+                    return this.verifyConsensusWithFallback(votes, startTime);
+                }
+                // Agents are connected only when they share a verdict, so any split
+                // vote disconnects the graph (λ2 = 0) and fails verification here.
+                const isValid = collapseRisk < 0.3 && fiedlerValue > 0.1;
+                const isFalseConsensus = appearsFalselyUnified(tally);
+                let recommendation;
+                if (!isValid) {
+                    recommendation =
+                        `No verified consensus (${describeTally(tally)}): agreement-graph Fiedler value ` +
+                            `${fiedlerValue.toFixed(3)}, collapse risk ${collapseRisk.toFixed(2)}. Spawn independent reviewer.`;
+                }
+                else if (isFalseConsensus) {
+                    recommendation =
+                        `Consensus verified (${describeTally(tally)}), but unanimous agreement may indicate ` +
+                            'false consensus. Consider adding diversity.';
+                }
+                else {
+                    recommendation = `Consensus verified (${describeTally(tally)}).`;
+                }
                 return {
-                    isValid: collapseRisk < 0.3 && fiedlerValue > 0.1,
+                    isValid,
                     confidence: 1 - collapseRisk,
-                    isFalseConsensus: fiedlerValue < 0.05,
+                    isFalseConsensus,
                     fiedlerValue,
                     collapseRisk,
-                    recommendation: collapseRisk > 0.3
-                        ? 'Spawn independent reviewer'
-                        : 'Consensus verified',
+                    recommendation,
                     durationMs: Date.now() - startTime,
                     usedFallback: false,
                 };
@@ -586,30 +640,36 @@ export class CoherenceService {
      * Fallback consensus verification
      */
     verifyConsensusWithFallback(votes, startTime) {
-        // Count verdicts
-        const verdictCounts = new Map();
-        for (const vote of votes) {
-            const key = String(vote.verdict);
-            verdictCounts.set(key, (verdictCounts.get(key) || 0) + 1);
-        }
-        // Find majority
-        let maxCount = 0;
-        verdictCounts.forEach(count => {
-            maxCount = Math.max(maxCount, count);
-        });
-        const majorityRatio = maxCount / votes.length;
+        const tally = tallyVotes(votes);
+        const { majorityRatio } = tally;
         const avgConfidence = votes.reduce((sum, v) => sum + v.confidence, 0) / votes.length;
+        // Flags and text are derived from the same predicates so the
+        // recommendation can never contradict them (issue #535).
+        const isValid = majorityRatio > FALLBACK_MAJORITY_THRESHOLD;
+        const isFalseConsensus = appearsFalselyUnified(tally);
+        let recommendation;
+        if (!isValid) {
+            recommendation =
+                `No clear majority: ${describeBreakdown(tally)} across ${tally.total} votes ` +
+                    `(needs more than ${Math.round(FALLBACK_MAJORITY_THRESHOLD * 100)}% agreeing). Consider spawning additional agents.`;
+        }
+        else if (isFalseConsensus) {
+            recommendation =
+                `Unanimous consensus (${describeLeader(tally)}) may indicate false consensus. Consider adding diversity.`;
+        }
+        else if (tally.isUnanimous) {
+            recommendation = `Unanimous consensus achieved (${describeLeader(tally)}).`;
+        }
+        else {
+            recommendation = `Majority consensus achieved (${describeTally(tally)}).`;
+        }
         return {
-            isValid: majorityRatio > 0.6,
+            isValid,
             confidence: majorityRatio * avgConfidence,
-            isFalseConsensus: verdictCounts.size === 1 && votes.length > 2,
+            isFalseConsensus,
             fiedlerValue: majorityRatio, // Approximation
             collapseRisk: 1 - majorityRatio,
-            recommendation: majorityRatio < 0.6
-                ? 'No clear majority. Consider spawning additional agents.'
-                : majorityRatio === 1 && verdictCounts.size === 1
-                    ? 'Unanimous consensus may indicate false consensus. Consider adding diversity.'
-                    : 'Majority consensus achieved.',
+            recommendation,
             durationMs: Date.now() - startTime,
             usedFallback: true,
         };

package/dist/integrations/coherence/vote-tally.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Agentic QE v3 - Consensus vote tally
+ *
+ * Counts verdicts once so that every consensus flag and every
+ * recommendation string is derived from the same numbers (issue #535).
+ */
+/** Minimal vote shape needed to tally verdicts */
+export interface TallyableVote {
+    verdict: string | number | boolean;
+}
+/** Verdict counts for a set of votes */
+export interface VoteTally {
+    /** Total number of votes */
+    total: number;
+    /** Verdicts with counts, most votes first (ties ordered by verdict) */
+    counts: Array<{
+        verdict: string;
+        count: number;
+    }>;
+    /** Verdict with the most votes (first in `counts`) */
+    topVerdict: string;
+    /** Number of votes for `topVerdict` */
+    topCount: number;
+    /** topCount / total (0 when there are no votes) */
+    majorityRatio: number;
+    /** True when every vote has the same verdict */
+    isUnanimous: boolean;
+}
+/**
+ * Tally votes by verdict. Verdicts are compared by their string form,
+ * matching how consensus has always grouped them.
+ */
+export declare function tallyVotes(votes: readonly TallyableVote[]): VoteTally;
+/** e.g. "2 of 3 votes 'pass'" */
+export declare function describeLeader(tally: VoteTally): string;
+/** e.g. "2 'pass' / 1 'fail'" */
+export declare function describeBreakdown(tally: VoteTally): string;
+//# sourceMappingURL=vote-tally.d.ts.map

package/dist/integrations/coherence/vote-tally.js

@@ -0,0 +1,39 @@
+/**
+ * Agentic QE v3 - Consensus vote tally
+ *
+ * Counts verdicts once so that every consensus flag and every
+ * recommendation string is derived from the same numbers (issue #535).
+ */
+/**
+ * Tally votes by verdict. Verdicts are compared by their string form,
+ * matching how consensus has always grouped them.
+ */
+export function tallyVotes(votes) {
+    const byVerdict = new Map();
+    for (const vote of votes) {
+        const key = String(vote.verdict);
+        byVerdict.set(key, (byVerdict.get(key) ?? 0) + 1);
+    }
+    const counts = [...byVerdict.entries()]
+        .map(([verdict, count]) => ({ verdict, count }))
+        .sort((a, b) => b.count - a.count || a.verdict.localeCompare(b.verdict));
+    const top = counts[0] ?? { verdict: '', count: 0 };
+    const total = votes.length;
+    return {
+        total,
+        counts,
+        topVerdict: top.verdict,
+        topCount: top.count,
+        majorityRatio: total > 0 ? top.count / total : 0,
+        isUnanimous: counts.length === 1,
+    };
+}
+/** e.g. "2 of 3 votes 'pass'" */
+export function describeLeader(tally) {
+    return `${tally.topCount} of ${tally.total} votes '${tally.topVerdict}'`;
+}
+/** e.g. "2 'pass' / 1 'fail'" */
+export function describeBreakdown(tally) {
+    return tally.counts.map(({ verdict, count }) => `${count} '${verdict}'`).join(' / ');
+}
+//# sourceMappingURL=vote-tally.js.map

package/dist/integrations/ruvector/brain-exporter.js

@@ -21,6 +21,7 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { safeJsonParse } from '../../shared/safe-json.js';
 import { sha256, queryAll, queryIterator, countRows, domainFilterForColumn, writeJsonl, writeJsonlStreaming, readJsonl, runImportTransaction, serializeRowBlobs, deserializeRowBlobs, mergeGenericRow, remapPatternReferences, mergeAppendOnlyRow, TABLE_CONFIGS, PK_COLUMNS, CONFIDENCE_COLUMNS, TIMESTAMP_COLUMNS, } from './brain-shared.js';
+import { appendBrainImportWitness } from './brain-import-audit.js';
 // ============================================================================
 // Internal helpers
 // ============================================================================
@@ -226,9 +227,17 @@ export function importBrain(db, containerPath, options) {
     const importAll = () => {
         const patternIds = new Map();
         const patternWinners = new Map();
+        let sourceWitnessRows = 0;
         for (const config of configs) {
             const filePath = join(dir, config.fileName);
             let rows = readJsonl(filePath, safeJsonParse);
+            if (config.tableName === 'witness_chain') {
+                // Source rows are signed/linked to a different store. Copying them into
+                // this live chain would make the first imported predecessor invalid.
+                sourceWitnessRows += rows.length;
+                skipped += rows.length;
+                continue;
+            }
             // Deserialize BLOBs from Base64
             if (config.blobColumns && config.blobColumns.length > 0) {
                 rows = rows.map(r => deserializeRowBlobs(r, config.blobColumns));
@@ -252,6 +261,14 @@ export function importBrain(db, containerPath, options) {
                 conflicts += result.conflicts;
             }
         }
+        appendBrainImportWitness(db, {
+            sourceChecksum: manifest.checksum,
+            sourceWitnessRows,
+            importedRecords: imported,
+            skippedRecords: skipped,
+            conflicts,
+        });
+        imported += 1;
     };
     runImportTransaction(db, options.dryRun ?? false, importAll);
     return { imported, skipped, conflicts };

package/dist/integrations/ruvector/brain-import-audit.d.ts

@@ -0,0 +1,20 @@
+/** Record a brain import without grafting another store's witness history. */
+import type Database from 'better-sqlite3';
+interface BrainImportAuditDetails {
+    sourceChecksum: string;
+    sourceWitnessRows: number;
+    importedRecords: number;
+    skippedRecords: number;
+    conflicts: number;
+}
+/**
+ * Call inside the import transaction, after merging all non-witness tables.
+ *
+ * Reuses WitnessChain's own hashing/serialization so the link format cannot
+ * drift from what WitnessChain.verify() checks. The row is intentionally left
+ * unsigned: the target DB may belong to a different project than the CWD, so
+ * the process-default signing key is not necessarily the target's key.
+ */
+export declare function appendBrainImportWitness(db: Database.Database, details: BrainImportAuditDetails): void;
+export {};
+//# sourceMappingURL=brain-import-audit.d.ts.map

package/dist/integrations/ruvector/brain-import-audit.js

@@ -0,0 +1,22 @@
+import { GENESIS_PREV_HASH, hashWith, serializeEntry, } from '../../audit/witness-chain.js';
+/**
+ * Call inside the import transaction, after merging all non-witness tables.
+ *
+ * Reuses WitnessChain's own hashing/serialization so the link format cannot
+ * drift from what WitnessChain.verify() checks. The row is intentionally left
+ * unsigned: the target DB may belong to a different project than the CWD, so
+ * the process-default signing key is not necessarily the target's key.
+ */
+export function appendBrainImportWitness(db, details) {
+    const algo = 'shake256';
+    const actionData = JSON.stringify(details);
+    const last = db.prepare('SELECT * FROM witness_chain ORDER BY id DESC LIMIT 1')
+        .get();
+    const previousHash = last ? hashWith(algo, serializeEntry(last)) : GENESIS_PREV_HASH;
+    db.prepare(`
+    INSERT INTO witness_chain
+      (prev_hash, action_hash, action_type, action_data, timestamp, actor, hash_algo)
+    VALUES (?, ?, 'BRAIN_IMPORT', ?, ?, 'brain-import', ?)
+  `).run(previousHash, hashWith(algo, actionData), actionData, new Date().toISOString(), algo);
+}
+//# sourceMappingURL=brain-import-audit.js.map

package/dist/integrations/ruvector/brain-rvf-exporter.js

@@ -7,6 +7,7 @@ import { existsSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSyn
 import { basename, dirname, join, resolve } from 'path';
 import { createRvfStore, openRvfStore, openRvfStoreReadonly, isRvfNativeAvailable, } from './rvf-native-adapter.js';
 import { sha256, tableExists, queryAll, domainFilterForColumn, runImportTransaction, mergeGenericRow, remapPatternReferences, mergeAppendOnlyRow, TABLE_CONFIGS, TABLE_BLOB_COLUMNS, PK_COLUMNS, CONFIDENCE_COLUMNS, TIMESTAMP_COLUMNS, serializeRowBlobs, deserializeRowBlobs, } from './brain-shared.js';
+import { appendBrainImportWitness } from './brain-import-audit.js';
 // --- Export ---
 /**
  * Sidecar suffixes that make up a complete store on disk. `''` is the store
@@ -401,11 +402,18 @@ export function importBrainFromRvf(db, rvfPath, options) {
         const importAll = () => {
             const patternIds = new Map();
             const patternWinners = new Map();
+            let sourceWitnessRows = 0;
             // Import in TABLE_CONFIGS order (FK-aware)
             for (const config of TABLE_CONFIGS) {
                 let rows = tablesMap[config.tableName];
                 if (!rows || !Array.isArray(rows))
                     continue;
+                if (config.tableName === 'witness_chain') {
+                    // A source chain cannot be grafted into another store's live chain.
+                    sourceWitnessRows += rows.length;
+                    skipped += rows.length;
+                    continue;
+                }
                 // Deserialize BLOBs
                 const blobCols = TABLE_BLOB_COLUMNS[config.tableName];
                 if (blobCols && blobCols.length > 0) {
@@ -434,6 +442,14 @@ export function importBrainFromRvf(db, rvfPath, options) {
                     conflicts += result.conflicts;
                 }
             }
+            appendBrainImportWitness(db, {
+                sourceChecksum: sha256(kernel.image.toString('utf-8')),
+                sourceWitnessRows,
+                importedRecords: imported,
+                skippedRecords: skipped,
+                conflicts,
+            });
+            imported += 1;
         };
         runImportTransaction(db, options.dryRun ?? false, importAll);
         // Compact after conflict resolution (best-effort)

package/dist/integrations/ruvector/brain-shared.js

@@ -408,7 +408,7 @@ export function runImportTransaction(db, dryRun, importer) {
             throw rollback;
     });
     try {
-        transaction();
+        transaction.immediate();
     }
     catch (error) {
         if (error !== rollback)

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

@@ -10,7 +10,7 @@
  * intercepting pattern embedding writes/deletes/searches and routing them
  * to one or both backends depending on the configured mode.
  */
-import { getActiveEmbeddingSpaceIdentity } from '../../learning/real-embeddings.js';
+import { ensureEndpointEmbeddingSpaceIdentity, getActiveEmbeddingSpaceIdentity } from '../../learning/real-embeddings.js';
 import { verifyOrCreateEmbeddingSpaceManifest } from '../../learning/embedding-space.js';
 /**
  * Wraps the real RvfNativeAdapter to conform to the simpler RvfStore interface.
@@ -97,6 +97,11 @@ export class RvfDualWriter {
                 this.rvfAvailable = false;
                 return;
             }
+            // #754: a later process opens brain.rvf before any embed call has
+            // initialized the (lazy) endpoint runtime; resolve its identity first.
+            if (!this.activeSpaceId()) {
+                await ensureEndpointEmbeddingSpaceIdentity();
+            }
             const { isRvfLockHeldError, removeStaleRvfLock, quarantineUnusableStore } = await import('./rvf-store-integrity.js');
             const tryOpen = () => {
                 try {

package/dist/integrations/ruvector/shared-rvf-adapter.d.ts

@@ -11,6 +11,14 @@
  * @module integrations/ruvector/shared-rvf-adapter
  */
 import type { RvfNativeAdapter, RvfCompactionResult, RvfStatus } from './rvf-native-adapter.js';
+/**
+ * The store is locked by a live process. The open ladder has already logged
+ * why it is degrading, so callers should not log it again (#574).
+ */
+export declare class RvfLiveLockError extends Error {
+    readonly lockError: unknown;
+    constructor(lockError: unknown);
+}
 /** @internal test-only seam */
 export declare function __setSharedRvfAdapterForTests(adapter: RvfNativeAdapter | null): void;
 /**
@@ -21,6 +29,19 @@ export declare function __setSharedRvfAdapterForTests(adapter: RvfNativeAdapter
  * @returns The shared adapter, or null if native bindings are unavailable
  */
 export declare function getSharedRvfAdapter(dataDir?: string, dimensions?: number): RvfNativeAdapter | null;
+/**
+ * Race-tolerant open-or-create.
+ * Tries open first (cheap, succeeds for the common case where init has
+ * already produced the file). On open failure we attempt create. On the
+ * concurrent-create loser, create itself fails with `FsyncFailed`; we
+ * retry open once more. Any final exception bubbles up to the caller.
+ *
+ * Also asserts `dim()` matches the caller-requested `dimensions` after
+ * open so silent dimension drift between releases / configs is detected
+ * — a bad-dim file is closed and create() is attempted (fail-loud rather
+ * than corrupt-silently, which would manifest as wrong vector hits later).
+ */
+declare function openOrCreateRvf(openFn: (p: string) => RvfNativeAdapter, createFn: (p: string, dim: number) => RvfNativeAdapter, rvfPath: string, dimensions: number): RvfNativeAdapter;
 export interface CompactDecision {
     shouldCompact: boolean;
     trigger: 'force' | 'size-guard' | 'dead-ratio' | 'none';
@@ -64,6 +85,8 @@ export declare function compactSharedRvfAdapter(opts?: {
  * `getSharedRvfAdapter()` which invokes it internally.
  */
 export declare function runBootCompactGuard(adapter: RvfNativeAdapter, rvfPath: string): RvfCompactionResult | null;
+/** @internal test-only seam: the open ladder with injectable open/create */
+export { openOrCreateRvf as __openOrCreateRvfForTests };
 /** Close the shared adapter and reset the singleton. */
 export declare function resetSharedRvfAdapter(): void;
 //# sourceMappingURL=shared-rvf-adapter.d.ts.map

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

@@ -18,6 +18,18 @@ import { findProjectRoot } from '../../kernel/project-root.js';
 import { quarantineUnusableStore, isLockHeldByLiveProcess, isRvfLockHeldError, removeStaleRvfLock, readLockOwnerPid, } from './rvf-store-integrity.js';
 let sharedAdapter = null;
 let initAttempted = false;
+/**
+ * The store is locked by a live process. The open ladder has already logged
+ * why it is degrading, so callers should not log it again (#574).
+ */
+export class RvfLiveLockError extends Error {
+    lockError;
+    constructor(lockError) {
+        super(lockError instanceof Error ? lockError.message : String(lockError));
+        this.lockError = lockError;
+        this.name = 'RvfLiveLockError';
+    }
+}
 // ---------------------------------------------------------------------------
 // Test seam: allow tests to install a fake adapter without going through the
 // native binding loader. NOT part of the public API — used by tests only.
@@ -97,6 +109,9 @@ export function getSharedRvfAdapter(dataDir = '.agentic-qe', dimensions = 384) {
         return sharedAdapter;
     }
     catch (error) {
+        // Already reported by the open ladder as "locked by a live process".
+        if (error instanceof RvfLiveLockError)
+            return null;
         console.warn('[RVF] Shared adapter init failed:', error instanceof Error ? error.message : error);
         return null;
     }
@@ -137,12 +152,14 @@ 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.
+    let liveOwner = false;
     if (!opened && isRvfLockHeldError(openErr)) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             const fs = require('fs');
             const lockPath = `${rvfPath}.lock`;
             if (fs.existsSync(lockPath) && isLockHeldByLiveProcess(rvfPath)) {
+                liveOwner = true;
                 console.warn(`[RVF] ${rvfPath} is locked by a live process (pid ${readLockOwnerPid(rvfPath)}) — ` +
                     'not breaking the lock; degrading to SQLite for this run.');
             }
@@ -159,6 +176,11 @@ function openOrCreateRvf(openFn, createFn, rvfPath, dimensions) {
             }
         }
     }
+    // #574: a live owner means the store is busy, not missing or broken. A
+    // create on an existing path always fails and a reopen hits the same lock,
+    // so stop at the warning above instead of running Passes 2 and 3.
+    if (liveOwner)
+        throw new RvfLiveLockError(openErr);
     if (opened) {
         const actualDim = opened.dimension();
         if (actualDim === dimensions)
@@ -312,6 +334,8 @@ function formatBytes(n) {
     }
     return `${v.toFixed(i === 0 ? 0 : 1)}${units[i]}`;
 }
+/** @internal test-only seam: the open ladder with injectable open/create */
+export { openOrCreateRvf as __openOrCreateRvfForTests };
 /** Close the shared adapter and reset the singleton. */
 export function resetSharedRvfAdapter() {
     if (sharedAdapter) {

package/dist/kernel/hybrid-backend.d.ts

@@ -175,5 +175,11 @@ export declare class HybridMemoryBackend implements MemoryBackend {
     private ensureInitialized;
     private cleanup;
 }
+/**
+ * Create the project memory backend exactly as the QE kernel does
+ * (<dataDir>/memory.db, WAL, 'qe-kernel' default namespace). Shared with the
+ * CLI's lightweight memory path so both always open the same store.
+ */
+export declare function createKernelMemoryBackend(dataDir: string): HybridMemoryBackend;
 export {};
 //# sourceMappingURL=hybrid-backend.d.ts.map

package/dist/kernel/hybrid-backend.js

@@ -10,6 +10,7 @@
  * backward compatibility with existing MemoryBackend interface.
  */
 import { getUnifiedMemory, DEFAULT_UNIFIED_MEMORY_CONFIG } from './unified-memory.js';
+import * as path from 'path';
 import { MEMORY_CONSTANTS } from './constants.js';
 import { LoggerFactory } from '../logging/index.js';
 const logger = LoggerFactory.create('hybrid-backend');
@@ -329,4 +330,21 @@ export class HybridMemoryBackend {
         }
     }
 }
+/**
+ * Create the project memory backend exactly as the QE kernel does
+ * (<dataDir>/memory.db, WAL, 'qe-kernel' default namespace). Shared with the
+ * CLI's lightweight memory path so both always open the same store.
+ */
+export function createKernelMemoryBackend(dataDir) {
+    return new HybridMemoryBackend({
+        sqlite: {
+            path: path.join(dataDir, 'memory.db'),
+            walMode: true,
+            poolSize: 3,
+            busyTimeout: MEMORY_CONSTANTS.BUSY_TIMEOUT_MS,
+        },
+        enableFallback: true,
+        defaultNamespace: 'qe-kernel',
+    });
+}
 //# sourceMappingURL=hybrid-backend.js.map