agentic-qe 3.14.6 → 3.14.8

package/dist/domains/test-generation/interfaces.d.ts

@@ -16,7 +16,14 @@ export interface ITestGenerationAPI {
     /** Learn patterns from existing tests */
     learnPatterns(request: ILearnPatternsRequest): Promise<Result<ILearnedPatterns, Error>>;
 }
+/** Caller-owned specifications; expected values are never inferred from source. */
+export interface BehaviorExample {
+    functionName: string;
+    args: unknown[];
+    expected: unknown;
+}
 export interface IGenerateTestsRequest {
+    behaviorExamples?: BehaviorExample[];
     sourceFiles: string[];
     testType: 'unit' | 'integration' | 'e2e';
     framework?: TestFramework;
@@ -41,7 +48,8 @@ export interface IGenerateTestsRequest {
 }
 export interface IGeneratedTests {
     tests: IGeneratedTest[];
-    coverageEstimate: number;
+    /** null means unmeasured; never coerce unknown coverage to measured zero. */
+    coverageEstimate: number | null;
     /** Human-readable pattern names, for display (reports, CLI output). */
     patternsUsed: string[];
     /** Real qe_patterns.id values for the same patterns, for usage/ADR-110 tracking. */
@@ -61,6 +69,8 @@ export interface IGeneratedTest {
     compilationErrors?: string[];
     /** ADR-051: Whether test was enhanced by LLM */
     llmEnhanced?: boolean;
+    generationMode?: 'behavior-examples' | 'scaffolding';
+    generationLimits?: string[];
     /** Test quality gate validation result (loki-mode Gates 8 & 9) */
     qualityGateResult?: TestQualityGateResult;
     /** ADR-062: Whether this test is a holdout test (not shown to developer, runs in CI only) */

package/dist/domains/test-generation/services/behavior-example-validation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Boundary validation for caller-supplied behavior examples (#787 / #795).
+ *
+ * Shared by the MCP handlers, the CLI `--behavior-examples` path and the
+ * domain service so every entry point rejects the same malformed input with
+ * the same message. Failures are `CallerInputError`s: they are the caller's
+ * problem, not a sign of an unhealthy test-generation domain, and must never
+ * count toward its circuit breaker.
+ *
+ * Only the shape is checked here. Whether `functionName` exists in the source
+ * and whether `args` matches its arity can only be decided against the parsed
+ * source (see behavior-examples.ts), which also throws `CallerInputError`.
+ *
+ * Kept free of heavy imports (no `typescript`) so boundary layers can use it.
+ */
+import type { BehaviorExample } from '../interfaces.js';
+/**
+ * JSON Schema for one `behaviorExamples` element. Single source of truth for
+ * every tool definition that advertises `behaviorExamples` (protocol server
+ * `test_generate_enhanced` and `qe/tests/generate`).
+ */
+export declare const BEHAVIOR_EXAMPLE_ITEM_SCHEMA: Record<string, unknown>;
+/**
+ * Throw unless `value` is plain JSON data that can be emitted as a literal:
+ * finite numbers (no -0), strings, booleans, null, arrays and plain objects,
+ * without cycles.
+ */
+export declare function assertBehaviorJsonValue(value: unknown, label?: string): void;
+/**
+ * Validate the shape of `behaviorExamples` at a system boundary.
+ *
+ * @returns the examples typed as `BehaviorExample[]`, or `undefined` when omitted
+ * @throws CallerInputError describing the first invalid entry
+ */
+export declare function validateBehaviorExamples(value: unknown): BehaviorExample[] | undefined;
+//# sourceMappingURL=behavior-example-validation.d.ts.map

package/dist/domains/test-generation/services/behavior-example-validation.js

@@ -0,0 +1,89 @@
+/**
+ * Boundary validation for caller-supplied behavior examples (#787 / #795).
+ *
+ * Shared by the MCP handlers, the CLI `--behavior-examples` path and the
+ * domain service so every entry point rejects the same malformed input with
+ * the same message. Failures are `CallerInputError`s: they are the caller's
+ * problem, not a sign of an unhealthy test-generation domain, and must never
+ * count toward its circuit breaker.
+ *
+ * Only the shape is checked here. Whether `functionName` exists in the source
+ * and whether `args` matches its arity can only be decided against the parsed
+ * source (see behavior-examples.ts), which also throws `CallerInputError`.
+ *
+ * Kept free of heavy imports (no `typescript`) so boundary layers can use it.
+ */
+import { CallerInputError } from '../../../shared/error-utils.js';
+const SHAPE_HINT = 'expected [{ "functionName": "add", "args": [2, 3], "expected": 5 }]';
+/**
+ * JSON Schema for one `behaviorExamples` element. Single source of truth for
+ * every tool definition that advertises `behaviorExamples` (protocol server
+ * `test_generate_enhanced` and `qe/tests/generate`).
+ */
+export const BEHAVIOR_EXAMPLE_ITEM_SCHEMA = {
+    type: 'object',
+    description: 'One caller-owned specification example',
+    properties: {
+        functionName: { type: 'string', description: 'Named export of the source file to call' },
+        args: { type: 'array', description: 'Positional JSON arguments; length must equal the function arity', items: {} },
+        expected: { description: 'Expected JSON return value (use null for a null result)' },
+    },
+    required: ['functionName', 'args', 'expected'],
+};
+/**
+ * Throw unless `value` is plain JSON data that can be emitted as a literal:
+ * finite numbers (no -0), strings, booleans, null, arrays and plain objects,
+ * without cycles.
+ */
+export function assertBehaviorJsonValue(value, label = 'Behavior example value') {
+    const visit = (v, seen) => {
+        if (v === null || typeof v === 'string' || typeof v === 'boolean')
+            return;
+        if (typeof v === 'number' && Number.isFinite(v) && !Object.is(v, -0))
+            return;
+        if (typeof v !== 'object' || seen.has(v)) {
+            throw new CallerInputError(`${label} must be finite JSON data (no undefined, functions, NaN/Infinity, cycles, or negative zero)`);
+        }
+        if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) {
+            throw new CallerInputError(`${label} must contain only plain JSON objects`);
+        }
+        seen.add(v);
+        for (const item of Array.isArray(v) ? Array.from(v) : Object.values(v))
+            visit(item, seen);
+        seen.delete(v);
+    };
+    visit(value, new Set());
+}
+/**
+ * Validate the shape of `behaviorExamples` at a system boundary.
+ *
+ * @returns the examples typed as `BehaviorExample[]`, or `undefined` when omitted
+ * @throws CallerInputError describing the first invalid entry
+ */
+export function validateBehaviorExamples(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new CallerInputError(`behaviorExamples must be an array; ${SHAPE_HINT}`);
+    }
+    value.forEach((example, index) => {
+        const at = `behaviorExamples[${index}]`;
+        if (typeof example !== 'object' || example === null || Array.isArray(example)) {
+            throw new CallerInputError(`${at} must be an object; ${SHAPE_HINT}`);
+        }
+        const record = example;
+        if (typeof record.functionName !== 'string' || record.functionName.trim() === '') {
+            throw new CallerInputError(`${at}.functionName must be a non-empty string`);
+        }
+        if (!Array.isArray(record.args)) {
+            throw new CallerInputError(`${at}.args must be an array of arguments`);
+        }
+        if (!Object.prototype.hasOwnProperty.call(record, 'expected')) {
+            throw new CallerInputError(`${at}.expected is required (use null for a null result)`);
+        }
+        assertBehaviorJsonValue(record.args, `${at}.args`);
+        assertBehaviorJsonValue(record.expected, `${at}.expected`);
+    });
+    return value;
+}
+//# sourceMappingURL=behavior-example-validation.js.map

package/dist/domains/test-generation/services/behavior-examples.d.ts

@@ -0,0 +1,8 @@
+import type { BehaviorExample } from '../interfaces.js';
+export declare function generateBehaviorExamples(source: string, sourceFile: string, importPath: string, framework: string, examples: BehaviorExample[] | undefined, testType: string): {
+    code: string;
+    limits: string[];
+    assertions: number;
+    mode: "behavior-examples" | "scaffolding";
+};
+//# sourceMappingURL=behavior-examples.d.ts.map

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/fleet-integration.js

@@ -122,12 +122,13 @@ export class FleetInitEnhancer {
                 enableVectorEmbeddings: true,
             });
             // Find all source files
-            const glob = await import('fast-glob');
-            const files = await glob.default([
+            const { glob } = await import('tinyglobby');
+            const files = await glob([
                 '**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.py'
             ], {
                 cwd: this.projectRoot,
                 ignore: ['node_modules/**', 'dist/**', 'coverage/**', '.agentic-qe/**'],
+                expandDirectories: false,
             });
             console.log(chalk.gray(`  Indexing ${files.length} files...`));
             // Index files