agentic-qe 3.9.14 → 3.9.16

package/dist/cli/completions/index.js

@@ -231,6 +231,23 @@ export const COMMANDS = {
             install: { options: ['--shell'] },
         },
     },
+    // Brain export/import/diff/search
+    brain: {
+        description: 'Export, import, and inspect QE brain state',
+        subcommands: {
+            export: { options: ['-o', '--output', '--format', '--db'] },
+            import: { options: ['-i', '--input', '--strategy', '--dry-run', '--db'] },
+            info: { options: ['-i', '--input'] },
+            diff: { options: ['--table', '--verbose', '--json'] },
+            search: { options: ['-i', '--input', '--table', '--domain', '--pattern-type', '--since', '--until', '-q', '--query', '-l', '--limit', '--json'] },
+            'witness-backfill': { options: ['--db'] },
+        },
+    },
+    // Native binding advisor
+    upgrade: {
+        description: 'Detect optional native bindings and recommend install / flag changes',
+        options: ['--json', '--strict'],
+    },
 };
 /**
  * Task types for completion
@@ -284,40 +301,40 @@ export function generateBashCompletion() {
 
 # Helper function to complete test files (*.test.ts, *.spec.ts, *.test.js, etc.)
 _aqe_complete_test_files() {
-    local cur="\$1"
+    local cur="$1"
     local IFS=$'\\n'
     local files=()
 
     # Complete test files with common test file patterns
     # Use find for more reliable glob matching across directories
-    if [[ -z "\$cur" || "\$cur" == "." ]]; then
+    if [[ -z "$cur" || "$cur" == "." ]]; then
         # No prefix - search from current directory
         while IFS= read -r file; do
-            files+=("\$file")
+            files+=("$file")
         done < <(find . -maxdepth 3 -type f \\( -name "*.test.ts" -o -name "*.spec.ts" -o -name "*.test.js" -o -name "*.spec.js" -o -name "*.test.tsx" -o -name "*.spec.tsx" \\) 2>/dev/null | head -30)
     else
         # Has prefix - use compgen with glob patterns
-        files+=(\$(compgen -f -X '!*.test.ts' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.spec.ts' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.test.js' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.spec.js' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.test.tsx' -- "\$cur" 2>/dev/null))
-        files+=(\$(compgen -f -X '!*.spec.tsx' -- "\$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.test.ts' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.spec.ts' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.test.js' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.spec.js' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.test.tsx' -- "$cur" 2>/dev/null))
+        files+=($(compgen -f -X '!*.spec.tsx' -- "$cur" 2>/dev/null))
     fi
 
     # Also include directories for navigation
-    COMPREPLY=(\$(compgen -d -- "\$cur"))
+    COMPREPLY=($(compgen -d -- "$cur"))
 
     # Add test files to completions
     for file in "\${files[@]}"; do
-        [[ -n "\$file" ]] && COMPREPLY+=("\$file")
+        [[ -n "$file" ]] && COMPREPLY+=("$file")
     done
 }
 
 # Helper function to complete directories
 _aqe_complete_directories() {
-    local cur="\$1"
-    COMPREPLY=( \$(compgen -d -- "$cur") )
+    local cur="$1"
+    COMPREPLY=( $(compgen -d -- "$cur") )
 }
 
 # Main completion function (version-agnostic name per ADR-042)
@@ -325,12 +342,13 @@ _aqe_completions() {
     local cur prev words cword
     _init_completion || return
 
-    local commands="init status health task agent domain protocol test coverage quality security code migrate hypergraph completions"
+    local commands="init status health task agent domain protocol test coverage quality security code migrate hypergraph completions brain upgrade"
     local task_subcmds="submit list cancel status"
     local agent_subcmds="list spawn"
     local domain_subcmds="list health"
     local protocol_subcmds="run"
     local completions_subcmds="bash zsh fish powershell install"
+    local brain_subcmds="export import info diff search witness-backfill"
     local code_actions="index search impact deps"
     local test_actions="generate execute"
 
@@ -663,6 +681,48 @@ _aqe_completions() {
                     ;;
             esac
             ;;
+        brain)
+            case "\${words[2]}" in
+                export)
+                    COMPREPLY=( $(compgen -W "-o --output --format --db" -- "$cur") )
+                    return
+                    ;;
+                import)
+                    COMPREPLY=( $(compgen -W "-i --input --strategy --dry-run --db" -- "$cur") )
+                    return
+                    ;;
+                info)
+                    COMPREPLY=( $(compgen -W "-i --input" -- "$cur") )
+                    return
+                    ;;
+                diff)
+                    COMPREPLY=( $(compgen -W "--table --verbose --json" -- "$cur") )
+                    return
+                    ;;
+                search)
+                    case "$prev" in
+                        --domain)
+                            COMPREPLY=( $(compgen -W "$domains" -- "$cur") )
+                            return
+                            ;;
+                    esac
+                    COMPREPLY=( $(compgen -W "-i --input --table --domain --pattern-type --since --until -q --query -l --limit --json" -- "$cur") )
+                    return
+                    ;;
+                witness-backfill)
+                    COMPREPLY=( $(compgen -W "--db" -- "$cur") )
+                    return
+                    ;;
+                *)
+                    COMPREPLY=( $(compgen -W "$brain_subcmds" -- "$cur") )
+                    return
+                    ;;
+            esac
+            ;;
+        upgrade)
+            COMPREPLY=( $(compgen -W "--json --strict" -- "$cur") )
+            return
+            ;;
         *)
             COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
             return
@@ -722,6 +782,8 @@ _aqe() {
         'hypergraph:Query the code knowledge hypergraph'
         'migrate:V2 to V3 migration'
         'completions:Generate shell completions'
+        'brain:Export, import, and inspect QE brain state'
+        'upgrade:Detect optional native bindings and recommend flags'
     )
 
     domains=(
@@ -1016,6 +1078,30 @@ _aqe() {
                             ;;
                     esac
                     ;;
+                brain)
+                    local -a brain_commands
+                    brain_commands=(
+                        'export:Export brain state to a portable file/directory'
+                        'import:Import a brain export into the local database'
+                        'info:Show manifest metadata for a brain export'
+                        'diff:Compare two brain exports'
+                        'search:Filtered search over a JSONL brain export'
+                        'witness-backfill:Create witness chain entries for legacy patterns'
+                    )
+                    _arguments -C \\
+                        '1:brain subcommand:->brain_cmd' \\
+                        '*::arg:->brain_args'
+                    case "$state" in
+                        brain_cmd)
+                            _describe -t commands 'brain subcommands' brain_commands
+                            ;;
+                    esac
+                    ;;
+                upgrade)
+                    _arguments \\
+                        '--json[Emit the report as JSON]' \\
+                        '--strict[Exit non-zero if any optional native is missing]'
+                    ;;
             esac
             ;;
     esac
@@ -1063,6 +1149,16 @@ complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_
 complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "impacted" -d "Find impacted tests"
 complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "gaps" -d "Find coverage gaps"
 complete -c aqe -n "__fish_use_subcommand" -a "migrate" -d "V2 to V3 migration"
+complete -c aqe -n "__fish_use_subcommand" -a "brain" -d "Export, import, and inspect QE brain state"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "export" -d "Export brain state"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "import" -d "Import a brain export"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "info" -d "Show manifest info"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "diff" -d "Compare two brain exports"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "search" -d "Filtered search over a JSONL brain export"
+complete -c aqe -n "__fish_seen_subcommand_from brain; and not __fish_seen_subcommand_from export import info diff search witness-backfill" -a "witness-backfill" -d "Backfill witness chain entries"
+complete -c aqe -n "__fish_use_subcommand" -a "upgrade" -d "Detect optional native bindings and recommend install / flag changes"
+complete -c aqe -n "__fish_seen_subcommand_from upgrade" -l json -d "Emit the report as JSON"
+complete -c aqe -n "__fish_seen_subcommand_from upgrade" -l strict -d "Exit non-zero if any optional native is missing"
 complete -c aqe -n "__fish_use_subcommand" -a "completions" -d "Generate shell completions"
 
 # Domains list
@@ -1267,6 +1363,8 @@ $script:AQE_COMMANDS = @{
     'hypergraph' = 'Query the code knowledge hypergraph'
     'migrate' = 'V2 to V3 migration'
     'completions' = 'Generate shell completions'
+    'brain' = 'Export, import, and inspect QE brain state'
+    'upgrade' = 'Detect optional native bindings and recommend flags'
 }
 
 Register-ArgumentCompleter -Native -CommandName 'aqe' -ScriptBlock {

package/dist/cli/handlers/brain-handler.d.ts

@@ -16,6 +16,8 @@ export declare class BrainHandler implements ICommandHandler {
     private executeExport;
     private executeImport;
     private executeInfo;
+    private executeDiff;
+    private executeSearch;
     private executeWitnessBackfill;
     getHelp(): string;
 }

package/dist/cli/handlers/brain-handler.js

@@ -6,7 +6,7 @@
  */
 import path from 'path';
 import chalk from 'chalk';
-import { exportBrain, importBrain, brainInfo, witnessBackfill, } from '../brain-commands.js';
+import { exportBrain, importBrain, brainInfo, brainDiff, brainSearch, witnessBackfill, } from '../brain-commands.js';
 // ============================================================================
 // Brain Handler
 // ============================================================================
@@ -56,6 +56,32 @@ export class BrainHandler {
             .action(async (options) => {
             await this.executeWitnessBackfill(options);
         });
+        brain
+            .command('diff')
+            .description('Compare two brain exports (JSONL directory or .rvf file)')
+            .argument('<a>', 'Path to first brain export')
+            .argument('<b>', 'Path to second brain export')
+            .option('--table <name>', 'Restrict comparison to a single table')
+            .option('--verbose', 'Show the IDs of added/removed/changed records', false)
+            .option('--json', 'Emit the diff as JSON to stdout', false)
+            .action(async (a, b, options) => {
+            await this.executeDiff(a, b, options);
+        });
+        brain
+            .command('search')
+            .description('Search a JSONL brain export with filters')
+            .requiredOption('-i, --input <path>', 'Path to brain export directory (JSONL)')
+            .option('--table <name>', 'Table to search (default: qe_patterns)')
+            .option('--domain <name...>', 'Restrict to one or more domains')
+            .option('--pattern-type <type>', 'Restrict to a specific pattern_type (qe_patterns only)')
+            .option('--since <iso>', 'Include rows with timestamp ≥ <iso>')
+            .option('--until <iso>', 'Include rows with timestamp ≤ <iso>')
+            .option('-q, --query <text>', 'Substring match across name + description (case-insensitive)')
+            .option('-l, --limit <n>', 'Maximum results to return', '20')
+            .option('--json', 'Emit results as JSON to stdout', false)
+            .action(async (options) => {
+            await this.executeSearch(options);
+        });
     }
     async executeExport(options) {
         try {
@@ -224,6 +250,51 @@ export class BrainHandler {
             await this.cleanupAndExit(1);
         }
     }
+    async executeDiff(a, b, options) {
+        try {
+            const result = await brainDiff(path.resolve(a), path.resolve(b), {
+                tableFilter: options.table,
+            });
+            if (options.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+                await this.cleanupAndExit(result.identical ? 0 : 1);
+                return;
+            }
+            renderDiff(result, options.verbose);
+            // Exit code convention: 0 when identical, 1 when differences exist.
+            await this.cleanupAndExit(result.identical ? 0 : 1);
+        }
+        catch (error) {
+            console.error(chalk.red('\n  Brain diff failed:'), error);
+            await this.cleanupAndExit(2);
+        }
+    }
+    async executeSearch(options) {
+        try {
+            const limit = parseLimit(options.limit);
+            const domains = normalizeDomainOption(options.domain);
+            const result = await brainSearch(path.resolve(options.input), {
+                table: options.table,
+                domains,
+                patternType: options.patternType,
+                since: options.since,
+                until: options.until,
+                query: options.query,
+                limit,
+            });
+            if (options.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+                await this.cleanupAndExit(result.totalMatched > 0 ? 0 : 3);
+                return;
+            }
+            renderSearch(result);
+            await this.cleanupAndExit(result.totalMatched > 0 ? 0 : 3);
+        }
+        catch (error) {
+            console.error(chalk.red('\n  Brain search failed:'), error);
+            await this.cleanupAndExit(2);
+        }
+    }
     async executeWitnessBackfill(options) {
         try {
             console.log(chalk.blue('\n  Running witness chain backfill...\n'));
@@ -258,6 +329,8 @@ Subcommands:
   export    Export brain state to a portable .rvf file or JSONL directory
   import    Import a brain export into the local database
   info      Show manifest metadata for an existing brain export
+  diff      Compare two brain exports (manifest always; record-level for JSONL)
+  search    Filtered search over a JSONL brain export
 
 Examples:
   aqe brain export -o .agentic-qe/brain.rvf
@@ -266,6 +339,9 @@ Examples:
   aqe brain import -i .agentic-qe/brain.rvf --strategy latest-wins
   aqe brain import -i .agentic-qe/brain.rvf --dry-run
   aqe brain info -i .agentic-qe/brain.rvf
+  aqe brain diff ./brain-a ./brain-b --verbose
+  aqe brain search -i ./brain-export --query oauth --domain test-generation
+  aqe brain search -i ./brain-export --since 2026-03-01 --limit 50 --json
 `;
     }
 }
@@ -285,6 +361,150 @@ function formatBytes(bytes) {
         return `${(bytes / 1024).toFixed(1)} KB`;
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+function parseLimit(raw) {
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return 20;
+    return n;
+}
+function normalizeDomainOption(value) {
+    if (value === undefined)
+        return undefined;
+    const arr = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const raw of arr) {
+        for (const part of raw.split(',')) {
+            const trimmed = part.trim();
+            if (trimmed)
+                out.push(trimmed);
+        }
+    }
+    return out.length > 0 ? out : undefined;
+}
+function renderDiff(result, verbose) {
+    console.log(chalk.blue('\n  Brain Diff\n'));
+    console.log(`  A:            ${chalk.cyan(result.pathA)}  (${result.formatA})`);
+    console.log(`  B:            ${chalk.cyan(result.pathB)}  (${result.formatB})`);
+    console.log(`  Versions:     ${chalk.cyan(result.manifestA.version)} → ${chalk.cyan(result.manifestB.version)}` +
+        (result.versionMatch ? chalk.gray(' (match)') : chalk.yellow(' (differ)')));
+    console.log(`  Checksums:    ${chalk.gray(result.manifestA.checksum.slice(0, 12))}… → ` +
+        `${chalk.gray(result.manifestB.checksum.slice(0, 12))}…` +
+        (result.checksumMatch ? chalk.gray(' (match)') : chalk.yellow(' (differ)')));
+    console.log(`  Exported:     ${chalk.gray(result.manifestA.exportedAt)} → ${chalk.gray(result.manifestB.exportedAt)}`);
+    console.log(`  Records:      ${chalk.cyan(result.manifestA.totalRecords)} → ${chalk.cyan(result.manifestB.totalRecords)} ` +
+        formatDelta(result.manifestB.totalRecords - result.manifestA.totalRecords));
+    if (result.domainsOnlyInA.length > 0 || result.domainsOnlyInB.length > 0) {
+        console.log(chalk.blue('\n  Domains:'));
+        if (result.domainsOnlyInA.length > 0) {
+            console.log(`    Only in A: ${chalk.yellow(result.domainsOnlyInA.join(', '))}`);
+        }
+        if (result.domainsOnlyInB.length > 0) {
+            console.log(`    Only in B: ${chalk.yellow(result.domainsOnlyInB.join(', '))}`);
+        }
+    }
+    if (!result.recordLevel) {
+        console.log(chalk.gray('\n  Note: record-level diff is only available when both sides are JSONL exports.\n' +
+            '        Per-table counts shown below; re-export with --format jsonl for added/removed/changed IDs.'));
+    }
+    console.log(chalk.blue('\n  Tables:'));
+    const changed = result.tableDiffs.filter(tableHasChange);
+    if (changed.length === 0) {
+        console.log(chalk.gray('    (no differences)'));
+    }
+    else {
+        for (const t of changed) {
+            console.log(`    ${t.tableName.padEnd(28)} ${chalk.cyan(String(t.countA).padStart(7))} → ` +
+                `${chalk.cyan(String(t.countB).padStart(7))} ${formatDelta(t.delta)}` +
+                formatRecordBuckets(t, verbose));
+            if (verbose) {
+                if (t.added && t.added.length > 0)
+                    printIdBucket('added', t.added);
+                if (t.removed && t.removed.length > 0)
+                    printIdBucket('removed', t.removed);
+                if (t.changed && t.changed.length > 0)
+                    printIdBucket('changed', t.changed);
+            }
+        }
+    }
+    console.log('');
+    if (result.identical) {
+        console.log(chalk.green('  Result: identical\n'));
+    }
+    else {
+        console.log(chalk.yellow('  Result: differences found\n'));
+    }
+}
+function tableHasChange(t) {
+    if (t.delta !== 0)
+        return true;
+    if (t.added && t.added.length > 0)
+        return true;
+    if (t.removed && t.removed.length > 0)
+        return true;
+    if (t.changed && t.changed.length > 0)
+        return true;
+    return false;
+}
+function formatDelta(delta) {
+    if (delta === 0)
+        return chalk.gray('(±0)');
+    if (delta > 0)
+        return chalk.green(`(+${delta})`);
+    return chalk.red(`(${delta})`);
+}
+function formatRecordBuckets(t, verbose) {
+    const parts = [];
+    if (t.added && t.added.length > 0)
+        parts.push(chalk.green(`+${t.added.length}`));
+    if (t.removed && t.removed.length > 0)
+        parts.push(chalk.red(`-${t.removed.length}`));
+    if (t.changed && t.changed.length > 0)
+        parts.push(chalk.yellow(`~${t.changed.length}`));
+    if (parts.length === 0)
+        return '';
+    if (verbose)
+        return '  ' + parts.join(' ');
+    return '  ' + chalk.gray('[') + parts.join(' ') + chalk.gray(']');
+}
+function printIdBucket(label, ids) {
+    const preview = ids.slice(0, 10).join(', ');
+    const suffix = ids.length > 10 ? chalk.gray(` …(+${ids.length - 10} more)`) : '';
+    console.log(`      ${chalk.gray(label + ':')} ${preview}${suffix}`);
+}
+function renderSearch(result) {
+    console.log(chalk.blue('\n  Brain Search\n'));
+    console.log(`  Input:      ${chalk.cyan(result.inputPath)}`);
+    console.log(`  Table:      ${chalk.cyan(result.table)}`);
+    console.log(`  Scanned:    ${chalk.cyan(result.totalScanned)}    ` +
+        `Matched: ${chalk.cyan(result.totalMatched)}    ` +
+        `Shown: ${chalk.cyan(result.hits.length)}` +
+        (result.truncated ? chalk.yellow(` (truncated to limit ${result.limit})`) : ''));
+    if (result.hits.length === 0) {
+        console.log(chalk.yellow('\n  No matching rows.\n'));
+        return;
+    }
+    console.log('');
+    for (const hit of result.hits) {
+        const header = chalk.cyan(hit.id) +
+            (hit.display.patternType ? chalk.gray(`  ${hit.display.patternType}`) : '') +
+            (hit.display.domain ? chalk.gray(`  [${hit.display.domain}]`) : '') +
+            (hit.display.confidence !== undefined
+                ? chalk.gray(`  conf=${hit.display.confidence.toFixed(2)}`)
+                : '');
+        console.log(`  ${header}`);
+        if (hit.display.name)
+            console.log(`    ${chalk.bold(hit.display.name)}`);
+        if (hit.display.description) {
+            const desc = hit.display.description.length > 200
+                ? hit.display.description.slice(0, 200) + '…'
+                : hit.display.description;
+            console.log(`    ${chalk.gray(desc)}`);
+        }
+        if (hit.display.updatedAt)
+            console.log(`    ${chalk.gray(hit.display.updatedAt)}`);
+        console.log('');
+    }
+}
 // ============================================================================
 // Factory
 // ============================================================================

package/dist/cli/index.js

@@ -47,7 +47,6 @@ console.log = (...args) => {
     originalConsoleLog(...args);
 };
 // Also redirect timestamped INFO/WARN/ERROR log lines (e.g. "[07:12:24.372] [INFO ]")
-const originalConsoleInfo = console.info.bind(console);
 console.info = (...args) => {
     process.stderr.write(args.map(String).join(' ') + '\n');
 };
@@ -249,6 +248,11 @@ registerLazyCommand(program, {
     description: 'Generate shell completions for aqe',
     factory: () => import('./commands/completions.js').then(m => m.createCompletionsCommand(cleanupAndExit)),
 });
+registerLazyCommand(program, {
+    name: 'upgrade',
+    description: 'Detect optional native bindings and recommend install / flag changes',
+    factory: () => import('./commands/upgrade.js').then(m => m.createUpgradeCommand(cleanupAndExit)),
+});
 registerLazyCommand(program, {
     name: 'fleet',
     description: 'Fleet operations with multi-agent progress tracking',

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

@@ -13,6 +13,21 @@
  *   - 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
+ * 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.
+ *
+ * This is NOT a minor-line pin. If a future Vibium 26.y release changes
+ * the primitives' expectations, the CI smoke gate (scripts/smoke-test.sh)
+ * is the belt-and-suspenders check.
+ *
+ * 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";
 /**
  * Spawner injected into {@link installBrowserEngine} so tests can mock the
  * shell-out without monkey-patching the child_process module (ESM namespaces
@@ -26,7 +41,7 @@ export type Spawner = (bin: string, args: string[], options: {
 export interface BrowserEngineInstallerOptions {
     /** Skip installation entirely (for --minimal or --no-browser-engine). */
     skip?: boolean;
-    /** Package name/version spec. Defaults to "vibium". */
+    /** Package name/version spec. Defaults to {@link DEFAULT_VIBIUM_SPEC}. */
     packageSpec?: string;
     /** Override the npm binary (default: "npm"). */
     npmBin?: string;
@@ -34,6 +49,8 @@ export interface BrowserEngineInstallerOptions {
     timeoutMs?: number;
     /** Test seam — inject a spawner to avoid hitting real processes. */
     spawner?: Spawner;
+    /** Test seam — inject a platform probe for cross-OS diagnostic tests. */
+    platformProbe?: PlatformProbe;
 }
 export type BrowserEngineInstallStatus = 'already-installed' | 'installed' | 'skipped' | 'install-failed' | 'npm-unavailable';
 export interface BrowserEngineInstallResult {
@@ -41,7 +58,49 @@ export interface BrowserEngineInstallResult {
     version?: string;
     message?: string;
     packageSpec: string;
+    /**
+     * Platform diagnostic emitted after a successful install. Present when
+     * the current host is one where Vibium's first-run Chrome auto-download
+     * is known to fail (e.g. Linux aarch64 at v26.3.x) and we were able to
+     * point at a system browser, or couldn't and are saying so explicitly.
+     */
+    platformHint?: PlatformHint;
+}
+export interface PlatformHint {
+    /**
+     * Short machine-readable tag for the condition being reported. Consumers
+     * can assert on this in tests or suppress the hint in known-good envs.
+     */
+    code: 'linux-arm64-system-chromium-found' | 'linux-arm64-no-system-chromium';
+    /** Single-line human message suitable for `console.warn`. */
+    message: string;
+    /**
+     * Optional filesystem path to a system browser binary the user can point
+     * Vibium at via `VIBIUM_BROWSER_PATH`.
+     */
+    browserPath?: string;
 }
+/**
+ * Injectable seam for `os.platform()` / `os.arch()`. Tests override this
+ * to simulate running on a different host.
+ */
+export interface PlatformProbe {
+    platform: () => NodeJS.Platform;
+    arch: () => string;
+    existsSync: (path: string) => boolean;
+}
+/**
+ * Build a platform hint for hosts where Vibium's first-run Chrome auto-
+ * download is known to fail. Today that's just Linux aarch64 at the
+ * pinned Vibium version (v26.3.x). Returns `undefined` when no hint
+ * applies, so callers can cheaply check for presence.
+ *
+ * Intentionally conservative: we don't mutate the user's env or create
+ * symlinks — we surface a diagnostic with an exact `VIBIUM_BROWSER_PATH`
+ * export the user can add. Silent modifications to system state are out
+ * of scope for an installer that runs during `aqe init`.
+ */
+export declare function diagnosePlatform(probe?: PlatformProbe): PlatformHint | undefined;
 /**
  * Detect whether `vibium` is already on PATH. Returns the version string
  * on success, `null` otherwise. Uses a short timeout because we don't want