agentic-qe 3.14.6 → 3.14.7

package/dist/domains/test-generation/services/behavior-examples.js

@@ -0,0 +1,65 @@
+import ts from 'typescript';
+import { CallerInputError } from '../../../shared/error-utils.js';
+import { assertBehaviorJsonValue, validateBehaviorExamples } from './behavior-example-validation.js';
+/** JSON-only data is emitted as a parsed string, never interpolated as source. */
+function literal(value) {
+    assertBehaviorJsonValue(value);
+    return `JSON.parse(${JSON.stringify(JSON.stringify(value))})`;
+}
+export function generateBehaviorExamples(source, sourceFile, importPath, framework, examples, testType) {
+    const supported = ['vitest', 'jest', 'node-test'].includes(framework) && testType === 'unit';
+    const ast = ts.createSourceFile(sourceFile, source, ts.ScriptTarget.Latest, true);
+    const diagnostics = ast.parseDiagnostics;
+    if (diagnostics.length)
+        throw new CallerInputError('Cannot generate behavior examples from syntactically invalid source');
+    const exports = new Map();
+    for (const node of ast.statements) {
+        if (!ts.canHaveModifiers(node) || !ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        if (ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword))
+            continue;
+        const add = (name, fn) => {
+            if (fn.body && !fn.asteriskToken && fn.parameters.every(p => ts.isIdentifier(p.name) && p.name.text !== 'this' && !p.dotDotDotToken && !p.questionToken && !p.initializer))
+                exports.set(name, fn.parameters.length);
+        };
+        if (ts.isFunctionDeclaration(node) && node.name)
+            add(node.name.text, node);
+        if (ts.isVariableStatement(node))
+            for (const decl of node.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name) && decl.initializer && (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)))
+                    add(decl.name.text, decl.initializer);
+            }
+    }
+    validateBehaviorExamples(examples);
+    if (examples?.length && !supported)
+        throw new CallerInputError('Behavior examples support unit tests with vitest, jest, or node-test only');
+    const limits = [];
+    if (importPath === './module-under-test')
+        limits.push('Inline source: save the source and replace ./module-under-test with its real import path before running.');
+    const lines = [framework === 'node-test' ? "import { test } from 'node:test';\nimport assert from 'node:assert/strict';" : framework === 'vitest' ? "import { test, expect } from 'vitest';" : "import { test, expect } from '@jest/globals';"];
+    if (!examples?.length) {
+        limits.push('Scaffolding only: supply behaviorExamples from a specification or trusted fixtures. No behavior or coverage has been verified.');
+        lines.push(`test.skip('Scaffolding: behaviorExamples required for ${exports.size} supported named exports', () => {});`);
+    }
+    else {
+        lines.push(`import * as subject from ${JSON.stringify(importPath)};`);
+        for (const [index, example] of examples.entries()) {
+            if (!example || typeof example.functionName !== 'string' || !exports.has(example.functionName))
+                throw new CallerInputError(`Behavior example ${index + 1} must target a named exported function with required simple parameters; '${String(example?.functionName)}' is not one (supported: ${[...exports.keys()].join(', ') || 'none'})`);
+            if (!Array.isArray(example.args) || example.args.length !== exports.get(example.functionName))
+                throw new CallerInputError(`Behavior example argument count does not match ${example.functionName}`);
+            if (!Object.prototype.hasOwnProperty.call(example, 'expected'))
+                throw new CallerInputError('Behavior example requires an explicit expected value');
+            const call = `await subject[${JSON.stringify(example.functionName)}](${Array.from(example.args).map(a => literal(a)).join(', ')})`;
+            const assertion = framework === 'node-test' ? `assert.deepStrictEqual(${call}, ${literal(example.expected)});` : `expect(${call}).toStrictEqual(${literal(example.expected)});`;
+            lines.push(`test(${JSON.stringify(`${example.functionName}: specification example ${index + 1}`)}, async () => { ${assertion} });`);
+        }
+        const uncovered = [...exports.keys()].filter(name => !examples.some(e => e.functionName === name));
+        if (uncovered.length)
+            limits.push(`No supplied behavior examples for: ${uncovered.join(', ')}`);
+        limits.push('Only supplied examples are asserted; coverage is unmeasured. Re-exports, default exports, classes, rest/default/destructured/optional parameters and thrown-error specifications are unsupported.');
+    }
+    return { code: `// ${limits.join('\n// ')}\n${lines.join('\n')}\n`, limits, assertions: examples?.length ?? 0,
+        mode: examples?.length ? 'behavior-examples' : 'scaffolding' };
+}
+//# sourceMappingURL=behavior-examples.js.map

package/dist/domains/test-generation/services/test-generator.d.ts

@@ -70,6 +70,7 @@ export declare class TestGeneratorService implements ITestGenerationService {
     private readonly config;
     private readonly memory;
     private readonly generatorFactory;
+    private readonly usesDefaultGenerator;
     private readonly tddGenerator;
     private readonly propertyTestGenerator;
     private readonly testDataGenerator;
@@ -164,7 +165,6 @@ export declare class TestGeneratorService implements ITestGenerationService {
     private extractModuleName;
     private getImportPath;
     private countAssertions;
-    private estimateCoverage;
     private storeGenerationMetadata;
 }
 /**

package/dist/domains/test-generation/services/test-generator.js

@@ -6,13 +6,15 @@
  * Uses TypeScript AST parser for code analysis
  * Delegates to specialized services for TDD, property tests, and test data
  */
+import { generateBehaviorExamples } from './behavior-examples.js';
+import { validateBehaviorExamples } from './behavior-example-validation.js';
 import { LoggerFactory } from '../../../logging/index.js';
 import { v4 as uuidv4 } from 'uuid';
 import * as fs from 'fs';
 import * as path from 'path';
 import ts from 'typescript';
 import { ok, err } from '../../../shared/types/index.js';
-import { toErrorMessage } from '../../../shared/error-utils.js';
+import { CallerInputError, toErrorMessage } from '../../../shared/error-utils.js';
 import { TestGeneratorFactory } from '../factories/test-generator-factory.js';
 import { TDDGeneratorService } from './tdd-generator.js';
 import { PropertyTestGeneratorService } from './property-test-generator.js';
@@ -83,6 +85,7 @@ export class TestGeneratorService {
     config;
     memory;
     generatorFactory;
+    usesDefaultGenerator;
     tddGenerator;
     propertyTestGenerator;
     testDataGenerator;
@@ -92,6 +95,7 @@ export class TestGeneratorService {
     constructor(dependencies, config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.memory = dependencies.memory;
+        this.usesDefaultGenerator = !dependencies.generatorFactory;
         this.generatorFactory = dependencies.generatorFactory || new TestGeneratorFactory();
         this.tddGenerator = dependencies.tddGenerator || new TDDGeneratorService();
         this.propertyTestGenerator = dependencies.propertyTestGenerator || new PropertyTestGeneratorService();
@@ -123,11 +127,11 @@ export class TestGeneratorService {
      * Enhance generated test code using LLM
      * Adds edge cases, improves assertions, and adds documentation
      */
-    async enhanceTestWithLLM(testCode, sourceCode, analysis, sourceFilePath, context) {
+    async enhanceTestWithLLM(testCode, sourceCode, analysis, sourceFilePath, context, showSourcePath = true) {
         if (!this.llmRouter)
             return { code: testCode, enhanced: false };
         try {
-            let prompt = this.buildTestEnhancementPrompt(testCode, sourceCode, analysis);
+            let prompt = this.buildTestEnhancementPrompt(testCode, sourceCode, analysis, showSourcePath ? sourceFilePath : undefined, context?.importPath);
             // Prepend historical edge case patterns if injector is available (loki-mode Item 5)
             if (this.edgeCaseInjector) {
                 try {
@@ -223,8 +227,17 @@ Return ONLY the enhanced test code, no explanations.`,
     /**
      * Build prompt for test enhancement
      */
-    buildTestEnhancementPrompt(testCode, sourceCode, analysis) {
-        let prompt = `## Source Code to Test:\n\`\`\`typescript\n${sourceCode}\n\`\`\`\n\n`;
+    buildTestEnhancementPrompt(testCode, sourceCode, analysis, sourceFilePath, importPath) {
+        let prompt = '';
+        if (sourceFilePath || importPath) {
+            prompt += '## Module Under Test:\n';
+            if (sourceFilePath)
+                prompt += `- Source file: ${sourceFilePath}\n`;
+            if (importPath)
+                prompt += `- Import it in the tests from: '${importPath}'\n`;
+            prompt += '\n';
+        }
+        prompt += `## Source Code to Test:\n\`\`\`typescript\n${sourceCode}\n\`\`\`\n\n`;
         prompt += `## Current Test Code:\n\`\`\`typescript\n${testCode}\n\`\`\`\n\n`;
         if (analysis) {
             if (analysis.functions.length > 0) {
@@ -303,6 +316,8 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
      */
     async generateTests(request) {
         try {
+            // Throws CallerInputError (caught below) for malformed examples.
+            validateBehaviorExamples(request.behaviorExamples);
             // Auto-detect language and framework if not provided (ADR-078)
             const resolved = resolveRequest({
                 sourceFiles: request.sourceFiles,
@@ -312,7 +327,10 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
             });
             const effectiveFramework = (request.framework || resolved?.framework || 'vitest');
             const effectiveLanguage = request.language || resolved?.language;
-            const { sourceFiles, testType, coverageTarget = this.config.coverageTargetDefault, patterns = [], } = request;
+            const { sourceFiles, testType, patterns = [], } = request;
+            if (request.behaviorExamples?.length && sourceFiles.length !== 1) {
+                return err(new CallerInputError('behaviorExamples requires exactly one source file'));
+            }
             if (sourceFiles.length === 0) {
                 return err(new Error('No source files provided'));
             }
@@ -335,7 +353,9 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
                     }
                 }
             }
-            const coverageEstimate = this.estimateCoverage(tests, coverageTarget);
+            // Generation does not execute or instrument the source. Assertion counts
+            // are not coverage evidence, including LLM-generated and empty results.
+            const coverageEstimate = null;
             await this.storeGenerationMetadata(tests, patternsUsed);
             return ok({
                 tests,
@@ -458,16 +478,41 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
             dependencies,
             similarCode,
         };
-        let testCode = generator.generateTests(context);
-        // ADR-051: Enhance with LLM if enabled and available.
+        const hasExamples = (originalRequest?.behaviorExamples?.length ?? 0) > 0;
+        const jsSource = /\.(?:[cm]?[jt]s|[jt]sx)$/i.test(sourceFile);
+        const deterministicEligible = (this.usesDefaultGenerator || hasExamples)
+            && testType === 'unit' && jsSource && ['vitest', 'jest', 'node-test'].includes(framework);
+        if (hasExamples && !deterministicEligible) {
+            throw new CallerInputError('Behavior examples require JavaScript/TypeScript and vitest, jest, or node-test');
+        }
+        const buildDeterministic = () => generateBehaviorExamples(sourceContent, sourceFile, originalRequest?.importPathOverrides?.[sourceFile] ?? path.resolve(sourceFile), framework, originalRequest?.behaviorExamples, testType);
+        // ADR-051: Enhance with LLM if enabled and available. Caller-supplied
+        // behavior examples are the oracle, so they are never rewritten by an LLM.
         // #567: `llmEnhanced` reflects whether the LLM actually produced the code,
         // not merely whether a router was configured — a broken provider must not
         // report AI-enhanced output it did not produce.
+        const willEnhance = this.isLLMEnhancementAvailable() && !!sourceContent && !hasExamples;
+        // #795: without fixtures the LLM must start from the framework template,
+        // which carries the real import line for the module under test. The
+        // zero-assertion scaffold is only emitted when no LLM output is used.
+        let deterministic = deterministicEligible && !willEnhance ? buildDeterministic() : undefined;
+        let testCode = deterministic?.code ?? generator.generateTests(context);
         let llmEnhanced = false;
-        if (this.isLLMEnhancementAvailable() && sourceContent) {
-            const result = await this.enhanceTestWithLLM(testCode, sourceContent, codeAnalysis, sourceFile, context);
-            testCode = result.code;
+        if (willEnhance) {
+            // An import override means `sourceFile` is a stand-in (the MCP handler's
+            // /tmp/aqe-temp-* copy of inline source). Do not show the LLM that path:
+            // it could echo it into the test in a form the temp-path rewrite misses.
+            const result = await this.enhanceTestWithLLM(testCode, sourceContent, codeAnalysis, sourceFile, context, originalRequest?.importPathOverrides?.[sourceFile] === undefined);
             llmEnhanced = result.enhanced;
+            if (llmEnhanced) {
+                testCode = result.code;
+            }
+            else if (deterministicEligible) {
+                // The LLM produced nothing usable: fall back to the honest scaffold,
+                // never to template assertions with guessed expected values (#787).
+                deterministic = buildDeterministic();
+                testCode = deterministic.code;
+            }
         }
         const test = {
             id: uuidv4(),
@@ -476,7 +521,8 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
             testFile,
             testCode,
             type: testType,
-            assertions: this.countAssertions(testCode),
+            assertions: deterministic && !llmEnhanced ? deterministic.assertions : this.countAssertions(testCode),
+            ...(!llmEnhanced && deterministic ? { generationMode: deterministic.mode, generationLimits: deterministic.limits } : {}),
             // ADR-078: Include detected language and framework
             language: effectiveLanguage,
             framework: framework,
@@ -976,23 +1022,6 @@ Return a JSON array of test suggestions, each with: { "name": "test name", "desc
         }
         return Math.max(1, count);
     }
-    estimateCoverage(tests, target) {
-        const totalAssertions = tests.reduce((sum, t) => sum + t.assertions, 0);
-        const totalTests = tests.length;
-        const testBasedCoverage = totalTests * 4;
-        const assertionCoverage = totalAssertions * 1.5;
-        const typeMultiplier = tests.reduce((mult, t) => {
-            if (t.type === 'integration')
-                return mult + 0.1;
-            if (t.type === 'e2e')
-                return mult + 0.15;
-            return mult;
-        }, 1);
-        const rawEstimate = (testBasedCoverage + assertionCoverage) * typeMultiplier;
-        const diminishedEstimate = rawEstimate * (1 - rawEstimate / 200);
-        const estimatedCoverage = Math.min(target, Math.max(0, diminishedEstimate));
-        return Math.round(estimatedCoverage * 10) / 10;
-    }
     async storeGenerationMetadata(tests, patterns) {
         const metadata = {
             generatedAt: new Date().toISOString(),

package/dist/domains/visual-accessibility/services/axe-core-audit.d.ts

@@ -1,18 +1,3 @@
-/**
- * Agentic QE v3 - Axe-Core Accessibility Audit
- *
- * Lightweight implementation using vibium + axe-core for accessibility testing.
- * Vibium provides browser automation via WebDriver BiDi (~202KB),
- * axe-core provides accessibility rules (~3MB).
- *
- * Features:
- * - WCAG 2.0/2.1/2.2 compliance testing
- * - Section 508 compliance
- * - Best practices validation
- * - Custom rule configuration
- *
- * @module visual-accessibility/axe-core-audit
- */
 /**
  * WCAG conformance levels
  */

package/dist/domains/visual-accessibility/services/axe-core-audit.js

@@ -1,3 +1,4 @@
+import { loadVibium, isVibiumReady, VIBIUM_SETUP } from '../../../integrations/vibium/runtime.js';
 /**
  * Agentic QE v3 - Axe-Core Accessibility Audit
  *
@@ -83,8 +84,8 @@ export class AccessibilityAuditor {
         }
         // Check for vibium
         try {
-            await import('vibium');
-            this.toolsAvailable.vibium = true;
+            await loadVibium();
+            this.toolsAvailable.vibium = isVibiumReady();
         }
         catch {
             this.toolsAvailable.vibium = false;
@@ -138,11 +139,12 @@ export class AccessibilityAuditor {
      * Run actual axe-core audit using vibium
      */
     async runAxeCoreAudit(startTime) {
-        const { browser } = await import('vibium');
-        let vibe = null;
+        const { browser } = await loadVibium();
+        let instance = null;
         try {
             // Launch browser
-            vibe = await browser.launch();
+            instance = await browser.start({ headless: true });
+            const vibe = await instance.page();
             // Navigate to URL
             await vibe.go(this.config.url);
             // Wait for selector if configured
@@ -153,12 +155,12 @@ export class AccessibilityAuditor {
             }
             // Inject axe-core library
             const axeSource = loadAxeCoreSource();
-            await vibe.evaluate(axeSource);
+            await vibe.addScript(axeSource);
             // Build axe configuration
             const axeConfig = this.buildAxeConfig();
             // Run axe-core audit
             const axeScript = `
-        return axe.run(${this.config.context ? `'${this.config.context}'` : 'document'}, ${JSON.stringify(axeConfig)});
+        axe.run(${this.config.context ? JSON.stringify(this.config.context) : 'document'}, ${JSON.stringify(axeConfig)})
       `;
             const results = await vibe.evaluate(axeScript);
             // Convert results
@@ -188,8 +190,8 @@ export class AccessibilityAuditor {
             };
         }
         finally {
-            if (vibe) {
-                await vibe.quit();
+            if (instance) {
+                await instance.stop();
             }
         }
     }
@@ -218,7 +220,7 @@ export class AccessibilityAuditor {
     createFallbackResult(startTime) {
         const errors = [];
         if (!this.toolsAvailable.vibium) {
-            errors.push('vibium is not installed. Install with: npm install vibium');
+            errors.push(`Vibium runtime or browser payload unavailable; run ${VIBIUM_SETUP}`);
         }
         if (!this.toolsAvailable.axeCore) {
             errors.push('axe-core is not installed. Install with: npm install axe-core');

package/dist/init/browser-engine-installer.d.ts

@@ -9,13 +9,13 @@
  * Design goals:
  *   - Graceful: never fail init if Vibium install fails; report and continue.
  *   - Idempotent: skip if Vibium is already on PATH.
- *   - Opt-out friendly: respect --minimal and --no-browser-engine flags.
+ *   - Opt-in only: called by init only with --browser-engine.
  *   - No new runtime deps: shells out to `npm install -g vibium` via child_process.
  */
 import { type SpawnSyncReturns } from 'node:child_process';
 /**
- * Default Vibium npm spec. Major-line pin via caret (`^26.3.18`) — npm
- * semver will accept any 26.x.y >= 26.3.18 but reject 27.0.0+. The intent
+ * Default Vibium npm spec. Major-line pin via caret (`^26.8.21`) — npm
+ * semver will accept any 26.x.y >= 26.8.21 but reject 27.0.0+. The intent
  * is to auto-receive security patches and additive minor features while
  * blocking breaking-change major bumps, which is where Vibium's CLI
  * contract (`go`, `--headless`, `viewport`, exit codes) can change.
@@ -27,7 +27,7 @@ import { type SpawnSyncReturns } from 'node:child_process';
  * Bump procedure: update this constant (e.g. to ^27.0.0 at a major), run
  * scripts/smoke-test.sh against the new version, then land the bump.
  */
-export declare const DEFAULT_VIBIUM_SPEC = "vibium@^26.3.18";
+export declare const DEFAULT_VIBIUM_SPEC = "vibium@^26.8.21";
 /**
  * Spawner injected into {@link installBrowserEngine} so tests can mock the
  * shell-out without monkey-patching the child_process module (ESM namespaces
@@ -66,7 +66,7 @@ export interface BrowserEngineInstallResult {
      */
     platformHint?: PlatformHint;
 }
-export type BrowserEngineDetectionStatus = 'ready' | 'cli-missing' | 'payload-missing';
+export type BrowserEngineDetectionStatus = 'ready' | 'cli-missing' | 'payload-missing' | 'unsupported-version';
 export interface BrowserEngineDetectionResult {
     status: BrowserEngineDetectionStatus;
     version?: string;

package/dist/init/browser-engine-installer.js

@@ -9,7 +9,7 @@
  * Design goals:
  *   - Graceful: never fail init if Vibium install fails; report and continue.
  *   - Idempotent: skip if Vibium is already on PATH.
- *   - Opt-out friendly: respect --minimal and --no-browser-engine flags.
+ *   - Opt-in only: called by init only with --browser-engine.
  *   - No new runtime deps: shells out to `npm install -g vibium` via child_process.
  */
 import { spawnSync as realSpawnSync } from 'node:child_process';
@@ -17,8 +17,8 @@ import * as os from 'node:os';
 import * as fs from 'node:fs';
 import { toErrorMessage } from '../shared/error-utils.js';
 /**
- * Default Vibium npm spec. Major-line pin via caret (`^26.3.18`) — npm
- * semver will accept any 26.x.y >= 26.3.18 but reject 27.0.0+. The intent
+ * Default Vibium npm spec. Major-line pin via caret (`^26.8.21`) — npm
+ * semver will accept any 26.x.y >= 26.8.21 but reject 27.0.0+. The intent
  * is to auto-receive security patches and additive minor features while
  * blocking breaking-change major bumps, which is where Vibium's CLI
  * contract (`go`, `--headless`, `viewport`, exit codes) can change.
@@ -30,7 +30,7 @@ import { toErrorMessage } from '../shared/error-utils.js';
  * Bump procedure: update this constant (e.g. to ^27.0.0 at a major), run
  * scripts/smoke-test.sh against the new version, then land the bump.
  */
-export const DEFAULT_VIBIUM_SPEC = 'vibium@^26.3.18';
+export const DEFAULT_VIBIUM_SPEC = 'vibium@^26.8.21';
 const defaultPlatformProbe = {
     platform: () => os.platform(),
     arch: () => os.arch(),
@@ -109,7 +109,7 @@ export function detectVibium(spawner = defaultSpawner, timeoutMs = 5_000) {
     const raw = stdout || stderr;
     if (!raw)
         return 'unknown';
-    // Extract first semver-looking token if present (e.g. "vibium version 26.3.18" → "26.3.18")
+    // Extract first semver-looking token if present (e.g. "vibium version 26.8.21" → "26.8.21")
     const match = raw.match(/v?(\d+\.\d+\.\d+(?:[-+][\w.]+)?)/);
     return match ? match[1] : raw.split(/\s+/)[0] || 'unknown';
 }
@@ -121,6 +121,15 @@ export function detectBrowserEngine(spawner = defaultSpawner, timeoutMs = 5_000)
     const version = detectVibium(spawner, timeoutMs);
     if (!version)
         return { status: 'cli-missing' };
+    // The modern JS adapter is supported only by stable 26.x releases >= 26.8.21.
+    const semver = /^(\d+)\.(\d+)\.(\d+)(?:\+[\w.]+)?$/.exec(version);
+    if (!semver || Number(semver[1]) !== 26 ||
+        Number(semver[2]) < 8 || (Number(semver[2]) === 8 && Number(semver[3]) < 21)) {
+        return {
+            status: 'unsupported-version', version,
+            message: `Vibium ${version} is unsupported; install ${DEFAULT_VIBIUM_SPEC} for the browser.start() API`,
+        };
+    }
     const payload = tryRun(spawner, 'vibium', ['is-installed'], timeoutMs);
     if (payload.status === 0)
         return { status: 'ready', version };
@@ -176,7 +185,20 @@ export function installBrowserEngine(options = {}) {
                 'unknown npm install failure',
         };
     }
-    const verified = detectBrowserEngine(spawner);
+    let verified = detectBrowserEngine(spawner);
+    if (verified.status === 'payload-missing') {
+        // Reinstalling an already-current npm package may not rerun postinstall.
+        // This installer is explicitly requested, so provision the payload directly.
+        const payloadInstall = tryRun(spawner, 'vibium', ['install'], timeoutMs);
+        if (payloadInstall.status !== 0) {
+            return {
+                status: 'install-failed', packageSpec, platformHint,
+                message: `Browser payload installation failed: ${payloadInstall.stderr?.trim() ||
+                    payloadInstall.stdout?.trim() || 'vibium install failed'}. Run \`vibium install\` and verify with \`vibium is-installed\`.`,
+            };
+        }
+        verified = detectBrowserEngine(spawner);
+    }
     if (verified.status !== 'ready') {
         const reason = verified.message ? `: ${verified.message}` : '';
         return {

package/dist/init/init-wizard.d.ts

@@ -16,6 +16,8 @@ export interface InitOrchestratorOptions {
     autoMode?: boolean;
     /** Skip pattern loading */
     skipPatterns?: boolean;
+    /** Explicitly install the optional browser engine and browser payload. */
+    browserEngine?: boolean;
     /** Minimal configuration */
     minimal?: boolean;
     /** Pre-trained patterns library */

package/dist/init/orchestrator.js

@@ -33,6 +33,7 @@ export class ModularInitOrchestrator {
                 skipPatterns: options.skipPatterns,
                 skipCodeIndex: options.skipCodeIndex,
                 minimal: options.minimal,
+                browserEngine: options.browserEngine,
                 withN8n: options.withN8n,
                 withOpenCode: options.withOpenCode,
                 withKiro: options.withKiro,

package/dist/init/phases/09-assets.js

@@ -79,19 +79,9 @@ export class AssetsPhase extends BasePhase {
             // Initialize overlay configs in agent registry for runtime use
             initializeOverlays(projectRoot);
         }
-        // Install Vibium browser engine for the qe-browser fleet skill.
-        // Graceful — never fails init if Vibium cannot be installed.
-        // Skipped in --minimal mode per ADR-086 minimal-footprint guidance.
-        //
-        // H6 (devil's-advocate finding): the install can take up to 3 minutes
-        // on cold caches because npm downloads Vibium AND lazily downloads a
-        // Chrome for Testing binary. spawnSync blocks the event loop, so the
-        // user sees no output for the entire duration. We log a clear pre-spawn
-        // message so users don't Ctrl-C thinking init hung. Future work: move
-        // this to a lazy/on-first-use install path so non-browser users never
-        // pay the cost.
+        // Browser setup is explicitly requested; normal init never downloads a browser.
         let browserEngine;
-        if (!options.minimal) {
+        if (options.browserEngine === true && !options.minimal) {
             try {
                 // Pre-flight check: if vibium is already on PATH, skip the loud
                 // banner so we don't scare users on the common path.
@@ -108,7 +98,7 @@ export class AssetsPhase extends BasePhase {
                 else {
                     // Not installed → we're about to spawn `npm install -g vibium`
                     // which can take 1–3 minutes on a cold cache. Tell the user.
-                    context.services.log('  Browser engine: installing vibium via npm (this can take 1–3 minutes on first run; downloads Chrome for Testing lazily)…');
+                    context.services.log('  Browser engine: installing vibium via npm (this can take 1–3 minutes on first run; downloads Chrome for Testing)…');
                     browserEngine = installBrowserEngine({ skip: false });
                     switch (browserEngine.status) {
                         case 'installed':
@@ -118,10 +108,10 @@ export class AssetsPhase extends BasePhase {
                             context.services.log('  Browser engine: skipped');
                             break;
                         case 'install-failed':
-                            context.services.warn(`Browser engine install failed (qe-browser skill will be unavailable until you run \`npm install -g vibium\`): ${browserEngine.message || 'unknown'}`);
+                            context.services.warn(`Browser engine install failed (qe-browser skill will be unavailable until you run \`aqe init --browser-engine\`): ${browserEngine.message || 'unknown'}`);
                             break;
                         case 'npm-unavailable':
-                            context.services.warn('Browser engine: npm not on PATH — install Node.js + npm, then `npm install -g vibium` to enable qe-browser');
+                            context.services.warn('Browser engine: npm not on PATH — install Node.js + npm, then `aqe init --browser-engine` to enable qe-browser');
                             break;
                         // 'already-installed' handled by the pre-flight branch above
                     }
@@ -141,12 +131,12 @@ export class AssetsPhase extends BasePhase {
                 const msg = error instanceof Error ? error.message : String(error);
                 context.services.warn(`Browser engine install error: ${msg}\n` +
                     `  qe-browser fleet skill will be unavailable until you run:\n` +
-                    `    npm install -g vibium\n` +
-                    `  Then re-run \`aqe init\` to verify. The rest of the AQE install will continue.`);
+                    `    npm install -g ${DEFAULT_VIBIUM_SPEC}\n` +
+                    `  Then re-run \`aqe init --browser-engine\` to verify. The rest of the AQE install will continue.`);
             }
         }
         else {
-            browserEngine = { status: 'skipped', packageSpec: DEFAULT_VIBIUM_SPEC, message: 'minimal mode' };
+            browserEngine = { status: 'skipped', packageSpec: DEFAULT_VIBIUM_SPEC, message: options.minimal ? 'minimal mode' : 'browser setup not requested; run aqe init --browser-engine' };
         }
         // Install n8n platform (optional)
         if (options.withN8n) {

package/dist/init/phases/phase-interface.d.ts

@@ -92,6 +92,8 @@ export interface InitOptions {
      */
     skipCodeIndex?: boolean;
     /** Minimal configuration (no skills, patterns, workers) */
+    /** Explicitly install the optional browser engine and browser payload. */
+    browserEngine?: boolean;
     minimal?: boolean;
     /** Automatically migrate from v2 if detected */
     /** Install n8n workflow testing platform */

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/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
      *