agentic-qe 3.15.4 → 3.15.6

package/dist/cli/commands/coverage.js

@@ -6,9 +6,12 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { runCoverageAnalysisWizard } from '../wizards/coverage-wizard.js';
-import { walkSourceFiles } from '../utils/file-discovery.js';
 import { writeOutput, toJSON, coverageToMarkdown } from '../utils/ci-output.js';
-import { buildCoverageData } from '../utils/coverage-data.js';
+import * as path from 'path';
+import { EXIT_UNMEASURED, coverageExitCode, coverageJson, evaluateCliCoverage, } from '../utils/coverage-verdict.js';
+// #1012 / #1010: resolution and verdict are shared with `aqe ci` (and built on
+// the same functions as MCP); re-exported here for existing importers.
+export { EXIT_UNMEASURED, resolveCliCoverageData } from '../utils/coverage-verdict.js';
 function getColorForPercent(percent) {
     if (percent >= 80)
         return chalk.green;
@@ -28,6 +31,27 @@ export function createCoverageCommand(context, cleanupAndExit, ensureInitialized
         .option('--ghost', 'Include ghost intent coverage analysis (detect untested behavioral intents)')
         .option('-F, --format <format>', 'Output format (text|json|markdown)', 'text')
         .option('-o, --output <path>', 'Write output to file')
+        .addHelpText('after', `
+Target: a directory, a source file, or an existing coverage report
+(lcov.info, coverage-final.json, coverage-summary.json, Cobertura XML).
+Reports are read from the target's project root (nearest package.json / .git).
+
+Threshold: judged on the metrics the report actually collected. A metric with
+no data (e.g. a report without branch data) is shown as n/a and is excluded
+from the threshold, not counted as 0%.
+
+Exit codes:
+  0  coverage meets the threshold (by more than 5%)
+  1  coverage below the threshold, or an error (missing target, unreadable report)
+  2  coverage within 5% above the threshold
+  ${EXIT_UNMEASURED}  UNMEASURED: no coverage measurement exists for the target
+     (not in the report, the runner ran 0 tests, or only test files were reported),
+     or NO coverage report exists, so only a labelled static estimate was shown
+     (-F json: measured:false, estimated:true; no threshold verdict)
+
+In \`aqe ci\`, an UNMEASURED coverage phase is a warning (phase exit code 3); it
+does not fail the pipeline by itself. An enforced quality gate fails on
+missing coverage evidence.`)
         .action(async (target, options) => {
         let analyzeTarget = target;
         let includeRisk = options.risk;
@@ -57,169 +81,189 @@ export function createCoverageCommand(context, cleanupAndExit, ensureInitialized
                 await cleanupAndExit(1);
             }
         }
-        if (!await ensureInitialized())
-            return;
+        // #995 review NB3: with a machine-readable format, stdout carries ONLY the
+        // document. Progress lines (ours, and anything printed while the fleet
+        // initializes) go to stderr; the real console.log is restored to emit.
+        const machineFormat = options.format !== 'text';
+        const stdoutLog = console.log;
+        if (machineFormat)
+            console.log = (...args) => console.error(...args);
+        const emit = (content) => {
+            console.log = stdoutLog;
+            writeOutput(content, options.output);
+        };
         try {
-            console.log(chalk.blue(`\n  Analyzing coverage for ${analyzeTarget}...\n`));
-            const coverageAPI = await context.kernel.getDomainAPIAsync('coverage-analysis');
-            if (!coverageAPI) {
-                console.log(chalk.red('Coverage analysis domain not available'));
+            if (!await ensureInitialized())
                 return;
-            }
-            const path = await import('path');
-            const targetPath = path.resolve(analyzeTarget);
-            // Fix #280: Use shared file discovery supporting all languages
-            const sourceFiles = walkSourceFiles(targetPath, { includeTests: false });
-            if (sourceFiles.length === 0) {
-                console.log(chalk.yellow('No source files found'));
-                return;
-            }
-            console.log(chalk.gray(`  Analyzing ${sourceFiles.length} files...\n`));
-            // Build coverage data from real V8/istanbul output or deterministic estimation
-            const coverageData = buildCoverageData(sourceFiles);
-            if (coverageData.instrumented) {
-                console.log(chalk.green('  Using instrumented coverage data (V8/istanbul)\n'));
-            }
-            else {
-                console.log(chalk.yellow('  No instrumented coverage found — using heuristic estimation'));
-                console.log(chalk.gray('  Run tests with coverage first: npm test -- --coverage\n'));
-            }
-            const result = await coverageAPI.analyze({
-                coverageData,
-                threshold,
-                includeFileDetails: true,
-            });
-            const format = options.format;
-            let coverageResult;
-            if (result.success && result.value) {
-                const report = result.value;
-                // For non-text formats, collect all data and output at end
-                coverageResult = {
-                    summary: report.summary,
-                    meetsThreshold: report.meetsThreshold,
-                    threshold,
-                    recommendations: report.recommendations,
-                };
+            try {
+                console.log(chalk.blue(`\n  Analyzing coverage for ${analyzeTarget}...\n`));
+                const coverageAPI = await context.kernel.getDomainAPIAsync('coverage-analysis');
+                if (!coverageAPI) {
+                    console.log(chalk.red('Coverage analysis domain not available'));
+                    return;
+                }
+                const targetPath = path.resolve(analyzeTarget);
+                // Fix #280: shared file discovery supporting all languages.
+                // #995: coverage files as targets; reports resolved from the project root.
+                // #1012: one shared verdict (measured / unmeasured / labelled estimate).
+                const outcome = await evaluateCliCoverage(coverageAPI, targetPath, threshold);
+                const format = options.format;
+                if (outcome.kind === 'no-sources') {
+                    console.log(chalk.yellow('No source files found'));
+                    return;
+                }
+                if (outcome.kind === 'error' || outcome.kind === 'unmeasured' || outcome.kind === 'analysis-failed') {
+                    // Errors (missing target, unreadable report) exit 1. "No measurement
+                    // exists" has its own exit code — never "0%".
+                    if (format === 'json') {
+                        // Same shape as a normal result, with nulls (#995 review N4).
+                        emit(toJSON(coverageJson(outcome, threshold, targetPath)));
+                    }
+                    else {
+                        console.log((outcome.kind === 'unmeasured' ? chalk.yellow : chalk.red)(`  ${outcome.message}\n`));
+                    }
+                    await cleanupAndExit(coverageExitCode(outcome, threshold));
+                    return;
+                }
+                const coverageData = outcome.data;
+                const isEstimate = outcome.kind === 'estimate';
+                if (!isEstimate) {
+                    console.log(chalk.green('  Using instrumented coverage data (V8/istanbul)\n'));
+                    if (coverageData.unmeasuredFiles?.length) {
+                        console.log(chalk.yellow(`  ${coverageData.unmeasuredFiles.length} file(s) not in the coverage report — UNMEASURED, excluded from the figures\n`));
+                    }
+                }
+                else {
+                    console.log(chalk.yellow('  No coverage report found — showing a heuristic STATIC ESTIMATE (UNMEASURED)'));
+                    console.log(chalk.gray('  Run tests with coverage first: npm test -- --coverage\n'));
+                }
+                // #1012: the JSON carries its provenance (measured / estimated /
+                // coverageMethod) exactly as MCP does; an estimate has no verdict.
+                const coverageResult = coverageJson(outcome, threshold, targetPath);
+                const summary = outcome.summary;
                 if (format === 'text') {
-                    const fmt = (v) => typeof v === 'number' ? v.toFixed(1) : v;
-                    console.log(chalk.cyan('  Coverage Summary:'));
-                    console.log(`    Lines:      ${getColorForPercent(report.summary.line)(fmt(report.summary.line) + '%')}`);
-                    console.log(`    Branches:   ${getColorForPercent(report.summary.branch)(fmt(report.summary.branch) + '%')}`);
-                    console.log(`    Functions:  ${getColorForPercent(report.summary.function)(fmt(report.summary.function) + '%')}`);
-                    console.log(`    Statements: ${getColorForPercent(report.summary.statement)(fmt(report.summary.statement) + '%')}`);
-                    console.log(`\n    Threshold: ${report.meetsThreshold ? chalk.green(`Met (${threshold}%)`) : chalk.red(`Not met (${threshold}%)`)}`);
-                    if (report.recommendations.length > 0) {
+                    const fmt = (v) => v === null ? 'n/a (not collected)' : (isEstimate ? '~' : '') + v.toFixed(1) + '%';
+                    const color = (v) => v === null || isEstimate ? chalk.gray : getColorForPercent(v);
+                    console.log(chalk.cyan(isEstimate ? '  Coverage Summary (STATIC ESTIMATE — not measured):' : '  Coverage Summary:'));
+                    console.log(`    Lines:      ${color(summary.line)(fmt(summary.line))}`);
+                    console.log(`    Branches:   ${color(summary.branch)(fmt(summary.branch))}`);
+                    console.log(`    Functions:  ${color(summary.function)(fmt(summary.function))}`);
+                    console.log(`    Statements: ${color(summary.statement)(fmt(summary.statement))}`);
+                    if (outcome.kind === 'measured') {
+                        console.log(`\n    Threshold: ${outcome.verdict.meetsThreshold ? chalk.green(`Met (${threshold}%)`) : chalk.red(`Not met (${threshold}%)`)}`);
+                    }
+                    else {
+                        console.log(`\n    Threshold: ${chalk.yellow(`not evaluated (${threshold}%) — UNMEASURED, estimate only`)}`);
+                        console.log(chalk.gray(`    ${outcome.message}`));
+                    }
+                    const recommendations = outcome.kind === 'measured' ? outcome.recommendations : [];
+                    if (recommendations.length > 0) {
                         console.log(chalk.cyan('\n  Recommendations:'));
-                        for (const rec of report.recommendations) {
+                        for (const rec of recommendations) {
                             console.log(chalk.gray(`    - ${rec}`));
                         }
                     }
                 }
-            }
-            // Detect gaps if requested
-            if (detectGaps) {
-                console.log(chalk.cyan('\n  Coverage Gaps:'));
-                const gapResult = await coverageAPI.detectGaps({
-                    coverageData,
-                    minCoverage: threshold,
-                    prioritize: includeRisk ? 'risk' : 'size',
-                });
-                if (gapResult.success && gapResult.value) {
-                    const gaps = gapResult.value;
-                    if (coverageResult)
+                // Detect gaps if requested
+                if (detectGaps) {
+                    console.log(chalk.cyan('\n  Coverage Gaps:'));
+                    const gapResult = await coverageAPI.detectGaps({
+                        coverageData,
+                        minCoverage: threshold,
+                        prioritize: includeRisk ? 'risk' : 'size',
+                        // #1014: gaps in an estimate are shown, never learned or published.
+                        measured: !isEstimate,
+                    });
+                    if (gapResult.success && gapResult.value) {
+                        const gaps = gapResult.value;
                         coverageResult.gaps = gaps.gaps.map(g => ({
                             file: g.file.replace(process.cwd() + '/', ''),
                             lines: g.lines,
                             riskScore: g.riskScore,
                             severity: g.severity,
                         }));
-                    console.log(chalk.gray(`    Total uncovered lines: ${gaps.totalUncoveredLines}`));
-                    console.log(chalk.gray(`    Estimated effort: ${gaps.estimatedEffort} hours\n`));
-                    for (const gap of gaps.gaps.slice(0, 8)) {
-                        const severityColor = gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
-                        const filePath = gap.file.replace(process.cwd() + '/', '');
-                        console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(filePath)}`);
-                        console.log(chalk.gray(`        ${gap.lines.length} uncovered lines, Risk: ${(gap.riskScore * 100).toFixed(0)}%`));
-                    }
-                    if (gaps.gaps.length > 8) {
-                        console.log(chalk.gray(`    ... and ${gaps.gaps.length - 8} more gaps`));
+                        console.log(chalk.gray(`    Total uncovered lines: ${gaps.totalUncoveredLines}`));
+                        console.log(chalk.gray(`    Estimated effort: ${gaps.estimatedEffort} hours\n`));
+                        for (const gap of gaps.gaps.slice(0, 8)) {
+                            const severityColor = gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
+                            const filePath = gap.file.replace(process.cwd() + '/', '');
+                            console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(filePath)}`);
+                            console.log(chalk.gray(`        ${gap.lines.length} uncovered lines, Risk: ${(gap.riskScore * 100).toFixed(0)}%`));
+                        }
+                        if (gaps.gaps.length > 8) {
+                            console.log(chalk.gray(`    ... and ${gaps.gaps.length - 8} more gaps`));
+                        }
                     }
                 }
-            }
-            // Ghost intent coverage analysis (ADR-059)
-            if (options.ghost || detectGaps) {
-                console.log(chalk.cyan('\n  Ghost Intent Coverage (ADR-059):'));
-                try {
-                    const testPaths = coverageData.files.map(f => f.path);
-                    const ghostResult = await coverageAPI.analyzeGhostCoverage(testPaths, analyzeTarget);
-                    if (ghostResult.success && ghostResult.value) {
-                        const ghost = ghostResult.value;
-                        console.log(chalk.gray(`    Phantom gaps detected: ${ghost.gaps.length}`));
-                        console.log(chalk.gray(`    Ghost score: ${(ghost.totalGhostScore * 100).toFixed(1)}%`));
-                        console.log(chalk.gray(`    Coverage completeness: ${(ghost.coverageCompleteness * 100).toFixed(1)}%\n`));
-                        for (const gap of ghost.gaps.slice(0, 8)) {
-                            const severityColor = gap.severity === 'critical' ? chalk.red : gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
-                            console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(gap.category)}`);
-                            console.log(chalk.gray(`        ${gap.description}`));
+                // Ghost intent coverage analysis (ADR-059)
+                if (options.ghost || detectGaps) {
+                    console.log(chalk.cyan('\n  Ghost Intent Coverage (ADR-059):'));
+                    try {
+                        const testPaths = coverageData.files.map(f => f.path);
+                        const ghostResult = await coverageAPI.analyzeGhostCoverage(testPaths, analyzeTarget);
+                        if (ghostResult.success && ghostResult.value) {
+                            const ghost = ghostResult.value;
+                            console.log(chalk.gray(`    Phantom gaps detected: ${ghost.gaps.length}`));
+                            console.log(chalk.gray(`    Ghost score: ${(ghost.totalGhostScore * 100).toFixed(1)}%`));
+                            console.log(chalk.gray(`    Coverage completeness: ${(ghost.coverageCompleteness * 100).toFixed(1)}%\n`));
+                            for (const gap of ghost.gaps.slice(0, 8)) {
+                                const severityColor = gap.severity === 'critical' ? chalk.red : gap.severity === 'high' ? chalk.red : gap.severity === 'medium' ? chalk.yellow : chalk.gray;
+                                console.log(`    ${severityColor(`[${gap.severity}]`)} ${chalk.white(gap.category)}`);
+                                console.log(chalk.gray(`        ${gap.description}`));
+                            }
+                            if (ghost.gaps.length > 8) {
+                                console.log(chalk.gray(`    ... and ${ghost.gaps.length - 8} more phantom gaps`));
+                            }
                         }
-                        if (ghost.gaps.length > 8) {
-                            console.log(chalk.gray(`    ... and ${ghost.gaps.length - 8} more phantom gaps`));
+                        else {
+                            console.log(chalk.dim('    Ghost analysis not available (requires HNSW index)'));
                         }
                     }
-                    else {
-                        console.log(chalk.dim('    Ghost analysis not available (requires HNSW index)'));
+                    catch {
+                        console.log(chalk.dim('    Ghost analysis skipped (analyzer not initialized)'));
                     }
                 }
-                catch {
-                    console.log(chalk.dim('    Ghost analysis skipped (analyzer not initialized)'));
-                }
-            }
-            // Calculate risk if requested
-            if (includeRisk) {
-                console.log(chalk.cyan('\n  Risk Analysis:'));
-                const lowCoverageFiles = [...coverageData.files]
-                    .sort((a, b) => (a.lines.covered / a.lines.total) - (b.lines.covered / b.lines.total))
-                    .slice(0, 5);
-                for (const file of lowCoverageFiles) {
-                    const riskResult = await coverageAPI.calculateRisk({
-                        file: file.path,
-                        uncoveredLines: file.uncoveredLines,
-                    });
-                    if (riskResult.success && riskResult.value) {
-                        const risk = riskResult.value;
-                        const riskColor = risk.riskLevel === 'high' ? chalk.red : risk.riskLevel === 'medium' ? chalk.yellow : chalk.green;
-                        const filePath = file.path.replace(process.cwd() + '/', '');
-                        console.log(`    ${riskColor(`[${risk.riskLevel}]`)} ${chalk.white(filePath)}`);
-                        console.log(chalk.gray(`        Risk: ${(risk.overallRisk * 100).toFixed(0)}%, Coverage: ${Math.round((file.lines.covered / file.lines.total) * 100)}%`));
+                // Calculate risk if requested
+                if (includeRisk) {
+                    console.log(chalk.cyan('\n  Risk Analysis:'));
+                    const lowCoverageFiles = [...coverageData.files]
+                        .sort((a, b) => (a.lines.covered / a.lines.total) - (b.lines.covered / b.lines.total))
+                        .slice(0, 5);
+                    for (const file of lowCoverageFiles) {
+                        const riskResult = await coverageAPI.calculateRisk({
+                            file: file.path,
+                            uncoveredLines: file.uncoveredLines,
+                        });
+                        if (riskResult.success && riskResult.value) {
+                            const risk = riskResult.value;
+                            const riskColor = risk.riskLevel === 'high' ? chalk.red : risk.riskLevel === 'medium' ? chalk.yellow : chalk.green;
+                            const filePath = file.path.replace(process.cwd() + '/', '');
+                            console.log(`    ${riskColor(`[${risk.riskLevel}]`)} ${chalk.white(filePath)}`);
+                            console.log(chalk.gray(`        Risk: ${(risk.overallRisk * 100).toFixed(0)}%, Coverage: ${Math.round((file.lines.covered / file.lines.total) * 100)}%`));
+                        }
                     }
                 }
+                // Non-text format output (collected all data)
+                if (format === 'json') {
+                    emit(toJSON(coverageResult));
+                }
+                else if (format === 'markdown') {
+                    emit(coverageToMarkdown(coverageResult));
+                }
+                else if (format === 'text') {
+                    console.log(chalk.green('\n Coverage analysis complete\n'));
+                }
+                // Exit codes: 1 = below threshold, 2 = within 5% of threshold,
+                // 0 = above threshold, 3 = UNMEASURED (estimate only) — shared with `aqe ci`.
+                await cleanupAndExit(coverageExitCode(outcome, threshold));
             }
-            // Non-text format output (collected all data)
-            if (coverageResult && format === 'json') {
-                writeOutput(toJSON(coverageResult), options.output);
-            }
-            else if (coverageResult && format === 'markdown') {
-                writeOutput(coverageToMarkdown(coverageResult), options.output);
-            }
-            else if (format === 'text') {
-                console.log(chalk.green('\n Coverage analysis complete\n'));
-            }
-            // Exit codes: 1 = below threshold, 2 = within 5% of threshold, 0 = above threshold
-            if (coverageResult && !coverageResult.meetsThreshold) {
+            catch (error) {
+                console.error(chalk.red('\nFailed:'), error);
                 await cleanupAndExit(1);
             }
-            if (coverageResult) {
-                const avg = (coverageResult.summary.line + coverageResult.summary.branch +
-                    coverageResult.summary.function + coverageResult.summary.statement) / 4;
-                if (avg < threshold + 5 && avg >= threshold) {
-                    await cleanupAndExit(2);
-                }
-            }
-            await cleanupAndExit(0);
         }
-        catch (error) {
-            console.error(chalk.red('\nFailed:'), error);
-            await cleanupAndExit(1);
+        finally {
+            console.log = stdoutLog;
         }
     });
     // Subcommand: coverage gaps — enumerate unhandled branches via static analysis

package/dist/cli/commands/daemon.js

@@ -70,7 +70,13 @@ Examples:
             // Fallback for environments where kernel isn't available
             const store = new Map();
             memory = {
-                async get(key) { return store.get(key); },
+                // Like InMemoryWorkerMemory (#1028 N4): this process-local store holds
+                // only daemon keys, so a read of another namespace finds nothing.
+                async get(key, options) {
+                    if (options?.namespace)
+                        return undefined;
+                    return store.get(key);
+                },
                 async set(key, value) { store.set(key, value); },
                 async search(pattern) {
                     const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');

package/dist/cli/commands/hooks-handlers/stats-hooks.d.ts

@@ -5,6 +5,21 @@
  * Handles pattern management and statistics subcommands.
  */
 import { Command } from 'commander';
+/**
+ * How a learned pattern reached vector search, by cause (#981, review N1).
+ * - `indexed`: stored with its vector in the active index.
+ * - `sqlite`: an embedder produced the vector and SQLite holds it (vector
+ *   search uses it now); only the ANN index (patterns.rvf) was not open in
+ *   this process. It is ingested automatically the next time the index opens.
+ * - `pending`: no vector (no embedding runtime); text search only until an
+ *   embedder is configured and `aqe learning backfill-embeddings` runs.
+ */
+export declare function describeVectorIndexState(pattern: {
+    embedding?: ArrayLike<number>;
+}, indexUnavailableCause?: string): {
+    vectorIndex: 'indexed' | 'sqlite' | 'pending';
+    notice?: string;
+};
 /**
  * Register stats, list, emit, learn, and search subcommands on the hooks command.
  */

package/dist/cli/commands/hooks-handlers/stats-hooks.js

@@ -7,7 +7,37 @@
 import chalk from 'chalk';
 import { QE_HOOK_EVENTS } from '../../../learning/qe-hooks.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { committedPendingIndexPatternId } from '../../../learning/pattern-mutation-error.js';
 import { getHooksSystem, printJson, printSuccess, printError, } from './hooks-shared.js';
+/**
+ * How a learned pattern reached vector search, by cause (#981, review N1).
+ * - `indexed`: stored with its vector in the active index.
+ * - `sqlite`: an embedder produced the vector and SQLite holds it (vector
+ *   search uses it now); only the ANN index (patterns.rvf) was not open in
+ *   this process. It is ingested automatically the next time the index opens.
+ * - `pending`: no vector (no embedding runtime); text search only until an
+ *   embedder is configured and `aqe learning backfill-embeddings` runs.
+ */
+export function describeVectorIndexState(pattern, indexUnavailableCause) {
+    const hasVector = Boolean(pattern.embedding && pattern.embedding.length > 0);
+    if (!hasVector) {
+        return {
+            vectorIndex: 'pending',
+            notice: 'Pattern stored in SQLite without a vector (no embedding runtime is available). ' +
+                'Text search finds it now. Set AQE_EMBEDDER_ENDPOINT or install @huggingface/transformers, then run ' +
+                '`aqe learning backfill-embeddings` to enable semantic search for it.',
+        };
+    }
+    if (indexUnavailableCause) {
+        return {
+            vectorIndex: 'sqlite',
+            notice: 'Pattern stored; its vector is stored in SQLite and vector search can use it now. ' +
+                `The ANN index (patterns.rvf) was not open in this process (${indexUnavailableCause}); ` +
+                'the vector is added to it automatically the next time the index opens.',
+        };
+    }
+    return { vectorIndex: 'indexed' };
+}
 /**
  * Register stats, list, emit, learn, and search subcommands on the hooks command.
  */
@@ -161,10 +191,27 @@ export function registerStatsHooks(hooks) {
                     tags: options.tags || [],
                 },
             });
+            // #981: COMMITTED_PENDING_INDEX means the authoritative SQLite row was
+            // written and only the derived vector index is unavailable (e.g. no
+            // embedding runtime). That is a stored pattern, not a failure.
+            let pattern = result.success ? result.value : null;
+            let indexCause;
             if (!result.success) {
-                throw new Error(result.error.message);
+                const committedId = committedPendingIndexPatternId(result.error);
+                if (!committedId) {
+                    throw new Error(result.error.message);
+                }
+                pattern = await reasoningBank.getPattern(committedId);
+                if (!pattern) {
+                    throw new Error(result.error.message);
+                }
+                const cause = result.error.cause;
+                indexCause = cause instanceof Error ? cause.message : 'the vector index is unavailable';
             }
-            const pattern = result.value;
+            if (!pattern) {
+                throw new Error('learn failed: no pattern returned');
+            }
+            const { vectorIndex, notice: pendingWarning } = describeVectorIndexState(pattern, indexCause);
             if (options.json) {
                 printJson({
                     success: true,
@@ -174,6 +221,8 @@ export function registerStatsHooks(hooks) {
                         type: pattern.patternType,
                         domain: pattern.qeDomain,
                     },
+                    vectorIndex,
+                    ...(pendingWarning ? { warning: pendingWarning } : {}),
                 });
             }
             else {
@@ -181,6 +230,9 @@ export function registerStatsHooks(hooks) {
                 console.log(chalk.dim(`  ID: ${pattern.id}`));
                 console.log(chalk.dim(`  Domain: ${pattern.qeDomain}`));
                 console.log(chalk.dim(`  Tier: ${pattern.tier}`));
+                if (pendingWarning) {
+                    console.log(chalk.yellow(`  ${vectorIndex === 'pending' ? 'Vector index pending' : 'Vector index'}: ${pendingWarning}`));
+                }
             }
         }
         catch (error) {