agentic-qe 3.14.5 → 3.14.7

package/dist/init/skills-installer.js

@@ -5,10 +5,11 @@
  * Installs AQE skills (both v2 methodology and v3 domain skills) to user projects.
  * Skills are copied from the bundled skills directory to the project's .claude/skills/.
  */
-import { existsSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync, copyFileSync, unlinkSync, rmdirSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, statSync, readFileSync, copyFileSync, unlinkSync, rmdirSync } from 'fs';
 import { join } from 'path';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { findPackageRoot } from './find-package-root.js';
+import { GENERATED_ON_LINE, writeTextIfChangedIgnoring } from './idempotent-write.js';
 // ============================================================================
 // Skill Categories (QE Skills Only - Claude Flow skills are managed separately)
 // ============================================================================
@@ -472,7 +473,8 @@ See \`.validation/README.md\` for usage instructions.
 
 *Generated by AQE v3 init on ${new Date().toISOString()}*
 `;
-        writeFileSync(join(skillsDir, 'README.md'), indexContent, 'utf-8');
+        // #778: ignore the generation-timestamp footer when deciding to rewrite.
+        writeTextIfChangedIgnoring(join(skillsDir, 'README.md'), indexContent, GENERATED_ON_LINE);
     }
     /**
      * Scan the skills directory to get all present skills

package/dist/init/types.d.ts

@@ -314,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/agentic-flow/reasoning-bank/index.d.ts

@@ -15,7 +15,7 @@
  * - Automatic strategy recommendations
  * - Pattern quality improvement over time
  */
-import { RealQEReasoningBank, type RealQEReasoningBankConfig, type RealQERoutingRequest, type RealQERoutingResult, type LearningOutcome } from '../../../learning/real-qe-reasoning-bank.js';
+import { RealQEReasoningBank, type RealQEReasoningBankConfig, type RealQEPatternSearchResult, type RealQERoutingRequest, type RealQERoutingResult, type LearningOutcome } from '../../../learning/real-qe-reasoning-bank.js';
 import { TrajectoryTracker, type Trajectory, type TrajectoryStep, type TrajectoryOptions, type TrajectoryTrackerConfig } from './trajectory-tracker.js';
 import { ExperienceReplay, type ExperienceGuidance, type ExperienceReplayConfig } from './experience-replay.js';
 import { PatternEvolution, type PatternVersion, type DriftDetectionResult, type MergeCandidate, type PatternEvolutionConfig } from './pattern-evolution.js';
@@ -182,10 +182,7 @@ export declare class EnhancedReasoningBankAdapter {
         limit?: number;
         domain?: QEDomain;
         minSimilarity?: number;
-    }): Promise<Result<Array<{
-        pattern: QEPattern;
-        similarity: number;
-    }>>>;
+    }): Promise<Result<RealQEPatternSearchResult[]>>;
     /**
      * Record a pattern outcome with evolution tracking
      */

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/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/integrations/vibium/client.d.ts

@@ -41,6 +41,7 @@ export declare class VibiumClientImpl implements VibiumClient {
     private _initialized;
     private _available;
     private vibeInstance;
+    private browserInstance;
     /**
      * Create a new Vibium client
      *

package/dist/integrations/vibium/client.js

@@ -7,6 +7,7 @@
  * @module integrations/vibium/client
  */
 import { randomUUID } from 'crypto';
+import { loadVibium, isVibiumReady, VIBIUM_SETUP } from './runtime.js';
 import { DEFAULT_VIBIUM_CONFIG } from './types.js';
 import { VibiumError, VibiumUnavailableError, VibiumTimeoutError, VibiumElementNotFoundError, VibiumConnectionError, VibiumNavigationError, VibiumScreenshotError, VibiumInteractionError, createVibiumError, } from './errors.js';
 import { toError } from '../../shared/error-utils.js';
@@ -24,7 +25,7 @@ async function getVibiumBrowser() {
         return vibiumBrowser;
     }
     try {
-        const vibium = await import('vibium');
+        const vibium = await loadVibium();
         vibiumBrowser = vibium.browser;
         vibiumAvailable = true;
         return vibiumBrowser;
@@ -112,6 +113,7 @@ export class VibiumClientImpl {
     _available = null;
     // Real Vibium browser instance
     vibeInstance = null;
+    browserInstance = null;
     /**
      * Create a new Vibium client
      *
@@ -133,7 +135,7 @@ export class VibiumClientImpl {
         try {
             // Check if Vibium package is available
             const browser = await getVibiumBrowser();
-            this._available = browser !== null;
+            this._available = browser !== null && isVibiumReady();
             return this._available;
         }
         catch {
@@ -157,7 +159,7 @@ export class VibiumClientImpl {
             if (isAvailable) {
                 this.lastHealthCheck = {
                     status: this.vibeInstance ? 'connected' : 'disconnected',
-                    version: '0.1.2', // From package.json
+                    // Runtime availability is checked against the installed payload.
                     browserType: this.config.browserType,
                     features: [
                         'browser-launch',
@@ -177,7 +179,7 @@ export class VibiumClientImpl {
                     status: 'unavailable',
                     features: ['fallback-only'],
                     lastChecked,
-                    error: 'Vibium package not available - install with: npm install vibium',
+                    error: `Vibium runtime or browser payload unavailable; run ${VIBIUM_SETUP}`,
                     sessionActive: false,
                 };
             }
@@ -209,13 +211,22 @@ export class VibiumClientImpl {
         const operation = async () => {
             const browser = await getVibiumBrowser();
             if (!browser) {
-                throw new VibiumUnavailableError('Vibium package not available. Install with: npm install vibium');
+                throw new VibiumUnavailableError(`Vibium runtime unavailable; run ${VIBIUM_SETUP}`);
             }
             // Launch REAL browser using Vibium
             const headless = options?.headless ?? this.config.headless;
-            this.vibeInstance = await browser.launch({
-                headless,
-            });
+            if (!isVibiumReady()) {
+                throw new VibiumUnavailableError(`Vibium browser payload unavailable; run ${VIBIUM_SETUP}`);
+            }
+            const instance = await browser.start({ headless });
+            try {
+                this.vibeInstance = await instance.page();
+                this.browserInstance = instance;
+            }
+            catch (error) {
+                await instance.stop();
+                throw error;
+            }
             const session = {
                 id: this.generateSessionId(),
                 browserType: this.config.browserType,
@@ -247,8 +258,9 @@ export class VibiumClientImpl {
         }
         const operation = async () => {
             if (this.vibeInstance) {
-                await this.vibeInstance.quit();
+                await this.browserInstance?.stop();
                 this.vibeInstance = null;
+                this.browserInstance = null;
             }
             this.currentSession = null;
         };
@@ -575,7 +587,7 @@ export class VibiumClientImpl {
         this.ensureSession();
         try {
             // Use real Vibium evaluate method
-            const result = await this.vibeInstance.evaluate(script);
+            const result = await this.vibeInstance.evaluate(`(async () => { ${script} })()`);
             return { success: true, value: result };
         }
         catch (error) {
@@ -608,13 +620,14 @@ export class VibiumClientImpl {
     async dispose() {
         if (this.vibeInstance) {
             try {
-                await this.vibeInstance.quit();
+                await this.browserInstance?.stop();
             }
             catch (error) {
                 // Non-critical: Vibium disposal errors
                 console.debug('[VibiumClient] Disposal error:', error instanceof Error ? error.message : error);
             }
             this.vibeInstance = null;
+            this.browserInstance = null;
         }
         this.currentSession = null;
         this._initialized = false;

package/dist/integrations/vibium/runtime.d.ts

@@ -0,0 +1,14 @@
+export declare const VIBIUM_SETUP = "aqe init --browser-engine (or npm install vibium@^26.8.21)";
+type Runtime = typeof import('vibium');
+/**
+ * How to run npm without a shell. On Windows `npm` is an `npm.cmd` shim, which
+ * execFile cannot start without `shell: true` (EINVAL/ENOENT since the
+ * CVE-2024-27980 fix), so run the npm CLI bundled next to node.exe instead.
+ * Falls back to plain `npm` when that layout is absent.
+ */
+export declare function npmInvocation(platform?: NodeJS.Platform, execPath?: string, exists?: (path: string) => boolean): [string, string[]];
+export declare function loadVibium(): Promise<Runtime>;
+/** Check the payload belonging to the resolved library, not a different PATH CLI. */
+export declare function isVibiumReady(): boolean;
+export {};
+//# sourceMappingURL=runtime.d.ts.map