agentic-qe 3.9.14 → 3.9.15

package/dist/cli/chunks/{witness-chain-LJUYOCB5.js → witness-chain-JE3QU4YP.js}

@@ -1,2 +1,2 @@
-import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.9.14");process.exit(0)}
-import{a,b,c,d,e,f,g}from"./chunk-4RDTR2OF.js";import"./chunk-STYNOKOM.js";import"./chunk-GUEK5DOK.js";import"./chunk-5HUAD4UU.js";import"./chunk-DGUAAG3T.js";export{c as PersistentWitnessChain,a as SPRTAccumulator,b as WitnessChain,f as createPersistentWitnessChain,e as createWitnessChain,d as createWitnessChainSQLitePersistence,g as isWitnessChainFeatureEnabled};
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.9.15");process.exit(0)}
+import{a,b,c,d,e,f,g}from"./chunk-ZHTCZGML.js";import"./chunk-FEVTMHO6.js";import"./chunk-XALB3KRR.js";import"./chunk-XXRDI53H.js";import"./chunk-CUQBOVRP.js";export{c as PersistentWitnessChain,a as SPRTAccumulator,b as WitnessChain,f as createPersistentWitnessChain,e as createWitnessChain,d as createWitnessChainSQLitePersistence,g as isWitnessChainFeatureEnabled};

package/dist/cli/chunks/{workflow-QORI3KO7.js → workflow-62QXGZQO.js}

@@ -1,5 +1,5 @@
-import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.9.14");process.exit(0)}
-import"./chunk-I5U64MHU.js";import{b as $}from"./chunk-OGLS6HB4.js";import{d as R}from"./chunk-VEAVDXXT.js";import{b as k,c as C,d as b}from"./chunk-OZBTC26R.js";import{c as W}from"./chunk-DMZ2XOEW.js";import"./chunk-PZF5ISGS.js";import"./chunk-UIYK4Y7K.js";import"./chunk-DGUAAG3T.js";import{Command as O}from"commander";import o from"chalk";function P(d,a){let m=d.indexOf("=");return m>0&&(a[d.substring(0,m)]=d.substring(m+1)),a}function x(d,a,m){let y=new O("workflow").description("Manage QE workflows and pipelines (ADR-041)");return y.command("run <file>").description("Execute a QE pipeline from YAML file").option("-w, --watch","Watch execution progress").option("-v, --verbose","Show detailed output").option("--params <json>","Additional parameters as JSON","{}").action(async(t,l)=>{if(!await m())return;let e=await import("fs"),c=(await import("path")).resolve(t);try{console.log(o.blue(`
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.9.15");process.exit(0)}
+import"./chunk-WCOJGDGO.js";import{b as $}from"./chunk-HWK27KJK.js";import{d as R}from"./chunk-D32YCVCA.js";import{b as k,c as C,d as b}from"./chunk-OMTYOIOS.js";import{c as W}from"./chunk-2XW36KDQ.js";import"./chunk-FW6QBTPE.js";import"./chunk-JJDHD7SC.js";import"./chunk-CUQBOVRP.js";import{Command as O}from"commander";import o from"chalk";function P(d,a){let m=d.indexOf("=");return m>0&&(a[d.substring(0,m)]=d.substring(m+1)),a}function x(d,a,m){let y=new O("workflow").description("Manage QE workflows and pipelines (ADR-041)");return y.command("run <file>").description("Execute a QE pipeline from YAML file").option("-w, --watch","Watch execution progress").option("-v, --verbose","Show detailed output").option("--params <json>","Additional parameters as JSON","{}").action(async(t,l)=>{if(!await m())return;let e=await import("fs"),c=(await import("path")).resolve(t);try{console.log(o.blue(`
  Running workflow from: ${t}
 `));let s=k(c);if(!s.success||!s.workflow){console.log(o.red("Failed to parse pipeline:"));for(let w of s.errors)console.log(o.red(`   ${w}`));await a(1)}let r={...W(l.params,"params")};if(s.pipeline){for(let w of s.pipeline.stages)if(w.params)for(let[S,h]of Object.entries(w.params))r[S]=h}if(!d.workflowOrchestrator.getWorkflow(s.workflow.id)){let w=d.workflowOrchestrator.registerWorkflow(s.workflow);w.success||(console.log(o.red(`Failed to register workflow: ${w.error.message}`)),await a(1))}let n=await d.workflowOrchestrator.executeWorkflow(s.workflow.id,r);if(!n.success){console.log(o.red(`Failed to start workflow: ${n.error.message}`)),await a(1);return}let p=n.value;if(console.log(o.cyan(`  Execution ID: ${p}`)),console.log(o.gray(`  Workflow: ${s.workflow.name}`)),console.log(o.gray(`  Stages: ${s.workflow.steps.length}`)),console.log(""),l.watch){console.log(o.blue(`Workflow Progress:
 `));let w,S=Date.now();for(;;){let g=d.workflowOrchestrator.getWorkflowStatus(p);if(!g)break;if(!w||w.progress!==g.progress||w.status!==g.status||JSON.stringify(w.currentSteps)!==JSON.stringify(g.currentSteps)){process.stdout.write("\r\x1B[K");let v="\u2588".repeat(Math.floor(g.progress/5))+"\u2591".repeat(20-Math.floor(g.progress/5)),D=g.status==="completed"?o.green:g.status==="failed"?o.red:g.status==="running"?o.yellow:o.gray;console.log(`  [${v}] ${g.progress}% - ${D(g.status)}`),g.currentSteps.length>0&&l.verbose&&console.log(o.gray(`    Running: ${g.currentSteps.join(", ")}`)),w=g}if(g.status==="completed"||g.status==="failed"||g.status==="cancelled")break;await new Promise(v=>setTimeout(v,500))}let h=d.workflowOrchestrator.getWorkflowStatus(p);if(h){console.log("");let g=h.duration||Date.now()-S;h.status==="completed"?(console.log(o.green("Workflow completed successfully")),console.log(o.gray(`   Duration: ${$(g)}`)),console.log(o.gray(`   Completed: ${h.completedSteps.length} stages`)),h.skippedSteps.length>0&&console.log(o.yellow(`   Skipped: ${h.skippedSteps.length} stages`))):h.status==="failed"?(console.log(o.red("Workflow failed")),console.log(o.red(`   Error: ${h.error}`)),console.log(o.gray(`   Failed stages: ${h.failedSteps.join(", ")}`))):console.log(o.yellow(`Workflow ${h.status}`))}}else console.log(o.green("Workflow execution started")),console.log(o.gray(`   Use 'aqe workflow status ${p}' to check progress`));console.log(""),await a(0)}catch(s){console.error(o.red(`
@@ -35,10 +35,10 @@ Workflow cancelled: ${t}
 `)):console.log(o.red(`
 Failed to cancel workflow: ${l.error.message}
 `)),await a(l.success?0:1)}catch(l){console.error(o.red(`
-Failed to cancel workflow:`),l),await a(1)}}),y.command("browser-list").description("List available browser workflow templates").action(async()=>{try{let{BrowserWorkflowTool:t}=await import("./browser-workflow-CSARLAJD.js"),e=await new t().invoke({});if(e.success&&e.data){console.log(o.blue(`
+Failed to cancel workflow:`),l),await a(1)}}),y.command("browser-list").description("List available browser workflow templates").action(async()=>{try{let{BrowserWorkflowTool:t}=await import("./browser-workflow-U4OON5DZ.js"),e=await new t().invoke({});if(e.success&&e.data){console.log(o.blue(`
  Browser Workflow Templates:
 `));for(let u of e.data.availableTemplates)console.log(`  ${o.cyan(u)}`);console.log("")}else console.log(o.red(`Failed: ${e.error||"Unknown error"}`));await a(0)}catch(t){console.error(o.red(`
-Failed:`),t),await a(1)}}),y.command("browser-load [template]").description("Load and validate a browser workflow template or inline YAML").option("--yaml <yaml>","Inline YAML workflow definition").option("-v, --var <key=value>","Variable override (repeatable)",P,{}).option("-F, --format <format>","Output format (text|json)","text").option("-o, --output <path>","Write output to file").action(async(t,l)=>{try{let{BrowserWorkflowTool:e}=await import("./browser-workflow-CSARLAJD.js"),{writeOutput:u,toJSON:c}=await import("./ci-output-QC4WRENA.js"),s=new e,f={variables:l.var||{}};if(l.yaml)f.workflowYaml=l.yaml;else if(t)if(t.endsWith(".yaml")||t.endsWith(".yml")){let i=await import("fs"),p=(await import("path")).resolve(t);i.existsSync(p)||(console.log(o.red(`
+Failed:`),t),await a(1)}}),y.command("browser-load [template]").description("Load and validate a browser workflow template or inline YAML").option("--yaml <yaml>","Inline YAML workflow definition").option("-v, --var <key=value>","Variable override (repeatable)",P,{}).option("-F, --format <format>","Output format (text|json)","text").option("-o, --output <path>","Write output to file").action(async(t,l)=>{try{let{BrowserWorkflowTool:e}=await import("./browser-workflow-U4OON5DZ.js"),{writeOutput:u,toJSON:c}=await import("./ci-output-CDFRGBNU.js"),s=new e,f={variables:l.var||{}};if(l.yaml)f.workflowYaml=l.yaml;else if(t)if(t.endsWith(".yaml")||t.endsWith(".yml")){let i=await import("fs"),p=(await import("path")).resolve(t);i.existsSync(p)||(console.log(o.red(`
 File not found: ${p}
 `)),await a(1)),f.workflowYaml=i.readFileSync(p,"utf-8")}else f.templateName=t;else console.log(o.red(`
 Provide a template name or --yaml. Use "workflow browser-list" to see templates.

package/dist/cli/chunks/workflow-orchestrator-RCR4N7OA.js

@@ -0,0 +1,2 @@
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.9.15");process.exit(0)}
+import{a,b,c,d}from"./chunk-AE65B2ZE.js";import"./chunk-ZOAPOVYW.js";import"./chunk-LLVS3UYZ.js";import"./chunk-KKBSX43Q.js";import"./chunk-FEVTMHO6.js";import"./chunk-XALB3KRR.js";import"./chunk-2XW36KDQ.js";import"./chunk-FW6QBTPE.js";import"./chunk-JJDHD7SC.js";import"./chunk-MBDX4OHD.js";import"./chunk-JAIIPEE6.js";import"./chunk-6OEGZSRK.js";import"./chunk-WI6UA5HV.js";import"./chunk-D3ZUSXFY.js";import"./chunk-2BBKAX7X.js";import"./chunk-MS6T4VCU.js";import"./chunk-IPVKVPAF.js";import"./chunk-YCYFUYCE.js";import"./chunk-XXRDI53H.js";import"./chunk-CUQBOVRP.js";export{b as DEFAULT_WORKFLOW_CONFIG,a as WorkflowEvents,c as WorkflowOrchestrator,d as createWorkflowOrchestrator};

package/dist/cli/chunks/{wrappers-3NR7LNB5.js → wrappers-CAX5EZSH.js}

@@ -1,2 +1,2 @@
-import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.9.14");process.exit(0)}
-import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v as L,w as M,x as N}from"./chunk-5MWNXDQW.js";import"./chunk-ZFZX2NA3.js";import"./chunk-UUVTLYUK.js";import"./chunk-STYNOKOM.js";import"./chunk-GUEK5DOK.js";import{a as v,b as w,c as x,d as y,e as z,f as A,g as B,h as C,i as D,j as E,k as F,l as G,m as H,n as I,o as J,p as K}from"./chunk-VU4QET3C.js";import"./chunk-DMZ2XOEW.js";import"./chunk-UIYK4Y7K.js";import"./chunk-LWHM5BWD.js";import"./chunk-J3XLOHWB.js";import"./chunk-JN7MSUGK.js";import"./chunk-JNLKLC7G.js";import"./chunk-WE7KIXR6.js";import"./chunk-XNXOW7BQ.js";import"./chunk-JLBUS4PR.js";import"./chunk-DJLRRCR6.js";import"./chunk-5HUAD4UU.js";import"./chunk-DGUAAG3T.js";export{z as GNNLayerFactory,i as QEFlashAttention,x as QEGNNEmbeddingIndex,y as QEGNNIndexFactory,a as QESONA,e as QE_FLASH_ATTENTION_CONFIG,g as QE_PERFORMANCE_TARGETS,f as QE_SONA_CONFIG,A as TensorCompressionFactory,u as batchComputeAttention,K as batchDifferentiableSearch,M as checkRuvectorPackagesAvailable,c as createDomainQESONA,j as createQEFlashAttention,b as createQESONA,D as getDifferentiableSearch,F as getGetCompressionLevel,E as getHierarchicalForward,G as getInit,h as getOptimalBlockConfig,k as getQEFlashAttentionConfig,n as getRuvectorDotProductAttention,m as getRuvectorFlashAttention,p as getRuvectorHyperbolicAttention,B as getRuvectorLayer,q as getRuvectorLinearAttention,r as getRuvectorMoEAttention,o as getRuvectorMultiHeadAttention,L as getRuvectorPackageVersions,C as getTensorCompress,l as getWorkloadTypes,N as initAllRuvectorPackages,w as initGNN,d as isAttentionAvailable,v as isGNNAvailable,s as toFloat32Array,H as toFloat32ArrayGNN,J as toIEmbedding,t as toNumberArrayAttn,I as toNumberArrayGNN};
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.9.15");process.exit(0)}
+import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v as L,w as M,x as N}from"./chunk-6TOUMCSE.js";import"./chunk-LLVS3UYZ.js";import"./chunk-KKBSX43Q.js";import"./chunk-FEVTMHO6.js";import"./chunk-XALB3KRR.js";import{a as v,b as w,c as x,d as y,e as z,f as A,g as B,h as C,i as D,j as E,k as F,l as G,m as H,n as I,o as J,p as K}from"./chunk-O6J7MKRV.js";import"./chunk-2XW36KDQ.js";import"./chunk-JJDHD7SC.js";import"./chunk-JAIIPEE6.js";import"./chunk-6OEGZSRK.js";import"./chunk-WI6UA5HV.js";import"./chunk-D3ZUSXFY.js";import"./chunk-2BBKAX7X.js";import"./chunk-MS6T4VCU.js";import"./chunk-IPVKVPAF.js";import"./chunk-YCYFUYCE.js";import"./chunk-XXRDI53H.js";import"./chunk-CUQBOVRP.js";export{z as GNNLayerFactory,i as QEFlashAttention,x as QEGNNEmbeddingIndex,y as QEGNNIndexFactory,a as QESONA,e as QE_FLASH_ATTENTION_CONFIG,g as QE_PERFORMANCE_TARGETS,f as QE_SONA_CONFIG,A as TensorCompressionFactory,u as batchComputeAttention,K as batchDifferentiableSearch,M as checkRuvectorPackagesAvailable,c as createDomainQESONA,j as createQEFlashAttention,b as createQESONA,D as getDifferentiableSearch,F as getGetCompressionLevel,E as getHierarchicalForward,G as getInit,h as getOptimalBlockConfig,k as getQEFlashAttentionConfig,n as getRuvectorDotProductAttention,m as getRuvectorFlashAttention,p as getRuvectorHyperbolicAttention,B as getRuvectorLayer,q as getRuvectorLinearAttention,r as getRuvectorMoEAttention,o as getRuvectorMultiHeadAttention,L as getRuvectorPackageVersions,C as getTensorCompress,l as getWorkloadTypes,N as initAllRuvectorPackages,w as initGNN,d as isAttentionAvailable,v as isGNNAvailable,s as toFloat32Array,H as toFloat32ArrayGNN,J as toIEmbedding,t as toNumberArrayAttn,I as toNumberArrayGNN};

package/dist/cli/commands/eval.js

@@ -14,7 +14,9 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as yaml from 'yaml';
 import { createParallelEvalRunner, DEFAULT_PARALLEL_EVAL_CONFIG, } from '../../validation/parallel-eval-runner.js';
+import { createCommandEvalRunner, isCommandEvalSuite, } from '../../validation/command-eval-runner.js';
 import { createSkillValidationLearner, } from '../../learning/skill-validation-learner.js';
 import { createRealQEReasoningBank, } from '../../learning/real-qe-reasoning-bank.js';
 // ============================================================================
@@ -185,6 +187,70 @@ function formatMarkdownReport(results) {
     return lines.join('\n');
 }
 // ============================================================================
+// Suite-shape dispatch
+// ============================================================================
+const DEFAULT_SKILLS_DIR = '.claude/skills';
+/**
+ * Peek at the eval yaml to decide whether the suite is command-mode
+ * (scripts producing JSON, per ADR-091) or LLM-mode (prompts evaluated by
+ * an LLM, the pre-existing shape). Returns null if the file is missing or
+ * unparseable; that error path is then surfaced by the respective runner.
+ */
+function detectSuiteMode(skill) {
+    const evalPath = path.join(process.cwd(), DEFAULT_SKILLS_DIR, skill, 'evals', `${skill}.yaml`);
+    if (!fs.existsSync(evalPath))
+        return null;
+    try {
+        const raw = yaml.parse(fs.readFileSync(evalPath, 'utf-8'));
+        return isCommandEvalSuite(raw) ? 'command' : 'llm';
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Adapt a {@link CommandEvalResult} into the {@link ParallelEvalResult} shape
+ * so the existing CLI formatting / reporting path works unchanged. Fields
+ * that don't apply to shell-command evals (model, reasoning quality,
+ * parallel speedup, worker count) are filled with sensible neutral values.
+ */
+function commandResultToParallel(cr, model) {
+    return {
+        skill: cr.skill,
+        model,
+        totalTests: cr.totalTests,
+        passedTests: cr.passedTests,
+        failedTests: cr.failedTests,
+        skippedTests: 0,
+        passRate: cr.passRate,
+        testResults: cr.testResults.map((t) => toParallelTestResult(t)),
+        totalDurationMs: cr.totalDurationMs,
+        parallelSpeedup: 1,
+        avgReasoningQuality: 0,
+        passed: cr.passed,
+        workersUsed: 1,
+        timestamp: cr.timestamp,
+    };
+}
+function toParallelTestResult(t) {
+    const errorParts = [];
+    if (t.setupFailure)
+        errorParts.push(t.setupFailure);
+    if (t.failures.length)
+        errorParts.push(...t.failures);
+    return {
+        testId: t.testId,
+        passed: t.passed,
+        expectedPatterns: [],
+        actualPatterns: [],
+        reasoningQuality: 0,
+        executionTimeMs: t.durationMs,
+        category: t.category ?? 'uncategorized',
+        priority: (t.priority ?? 'medium'),
+        error: errorParts.length ? errorParts.join('; ') : undefined,
+    };
+}
+// ============================================================================
 // Command Handlers
 // ============================================================================
 async function initializeRunner() {
@@ -209,6 +275,26 @@ async function initializeRunner() {
 async function handleRunCommand(options) {
     console.log(chalk.bold('\nAQE Parallel Eval Runner'));
     console.log(chalk.dim('ADR-056 Phase 5: Worker Pool Pattern\n'));
+    const suiteMode = detectSuiteMode(options.skill);
+    if (suiteMode === 'command') {
+        // Command-mode skills (e.g. qe-browser) don't need an LLM executor or a
+        // ReasoningBank. Keep them on a fast, dependency-light path.
+        console.log(chalk.cyan(`Running eval suite: ${options.skill}`));
+        console.log(chalk.dim('Mode: command-eval (shell-based, ADR-091)'));
+        console.log('');
+        const commandRunner = createCommandEvalRunner({
+            timeoutMs: options.timeout,
+        });
+        const commandResult = await commandRunner.run(options.skill);
+        const result = commandResultToParallel(commandResult, options.model);
+        console.log(formatResult(result));
+        if (options.output) {
+            const outputPath = path.resolve(options.output);
+            fs.writeFileSync(outputPath, JSON.stringify(result, null, 2));
+            console.log(chalk.green(`Results saved to: ${outputPath}`));
+        }
+        process.exit(result.passed ? 0 : 1);
+    }
     const { runner, reasoningBank } = await initializeRunner();
     try {
         // Configure runner

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

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

@@ -13,7 +13,74 @@
  *   - No new runtime deps: shells out to `npm install -g vibium` via child_process.
  */
 import { spawnSync as realSpawnSync } from 'node:child_process';
+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
+ * 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 const DEFAULT_VIBIUM_SPEC = 'vibium@^26.3.18';
+const defaultPlatformProbe = {
+    platform: () => os.platform(),
+    arch: () => os.arch(),
+    existsSync: (p) => fs.existsSync(p),
+};
+/**
+ * Candidate paths for a system chromium binary on Linux distributions that
+ * package Chromium (Debian, Ubuntu, Fedora, Arch). Order matters: we return
+ * the first match, so list the most common locations first.
+ */
+const LINUX_SYSTEM_CHROMIUM_PATHS = [
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/snap/bin/chromium',
+];
+/**
+ * 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 function diagnosePlatform(probe = defaultPlatformProbe) {
+    if (probe.platform() !== 'linux')
+        return undefined;
+    if (probe.arch() !== 'arm64')
+        return undefined;
+    const browserPath = LINUX_SYSTEM_CHROMIUM_PATHS.find((p) => probe.existsSync(p));
+    if (browserPath) {
+        return {
+            code: 'linux-arm64-system-chromium-found',
+            browserPath,
+            message: `Linux aarch64 detected. Vibium v26.3.x does not auto-download Chrome for Testing on ARM64. ` +
+                `Found system browser at ${browserPath}. Export VIBIUM_BROWSER_PATH=${browserPath} before running vibium.`,
+        };
+    }
+    return {
+        code: 'linux-arm64-no-system-chromium',
+        message: `Linux aarch64 detected. Vibium v26.3.x does not auto-download Chrome for Testing on ARM64, and no system ` +
+            `chromium was found on PATH (checked: ${LINUX_SYSTEM_CHROMIUM_PATHS.join(', ')}). ` +
+            `Install via \`apt-get install chromium\` (or your distro's equivalent), then export ` +
+            `VIBIUM_BROWSER_PATH=/usr/bin/chromium before running vibium.`,
+    };
+}
 function tryRun(spawner, bin, args, timeoutMs) {
     return spawner(bin, args, {
         encoding: 'utf8',
@@ -51,17 +118,20 @@ export function detectVibium(spawner = defaultSpawner, timeoutMs = 5_000) {
  * assets phase can log/summarize — never throws for expected failures.
  */
 export function installBrowserEngine(options = {}) {
-    const packageSpec = options.packageSpec || 'vibium';
+    const packageSpec = options.packageSpec || DEFAULT_VIBIUM_SPEC;
     if (options.skip) {
         return { status: 'skipped', packageSpec, message: 'install skipped by options' };
     }
     const spawner = options.spawner || defaultSpawner;
+    const platformProbe = options.platformProbe || defaultPlatformProbe;
+    const platformHint = diagnosePlatform(platformProbe);
     const alreadyInstalled = detectVibium(spawner);
     if (alreadyInstalled) {
         return {
             status: 'already-installed',
             version: alreadyInstalled,
             packageSpec,
+            platformHint,
         };
     }
     const npmBin = options.npmBin || 'npm';
@@ -71,7 +141,7 @@ export function installBrowserEngine(options = {}) {
         return {
             status: 'npm-unavailable',
             packageSpec,
-            message: 'npm is not available on PATH. Install Node.js + npm, then run `npm install -g vibium`.',
+            message: `npm is not available on PATH. Install Node.js + npm, then run \`npm install -g ${packageSpec}\`.`,
         };
     }
     const timeoutMs = options.timeoutMs || 180_000;
@@ -87,6 +157,6 @@ export function installBrowserEngine(options = {}) {
         };
     }
     const version = detectVibium(spawner) || 'unknown';
-    return { status: 'installed', version, packageSpec };
+    return { status: 'installed', version, packageSpec, platformHint };
 }
 //# sourceMappingURL=browser-engine-installer.js.map

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

@@ -8,7 +8,7 @@ import { BasePhase, } from './phase-interface.js';
 import { createSkillsInstaller } from '../skills-installer.js';
 import { createAgentsInstaller } from '../agents-installer.js';
 import { createN8nInstaller } from '../n8n-installer.js';
-import { installBrowserEngine } from '../browser-engine-installer.js';
+import { installBrowserEngine, DEFAULT_VIBIUM_SPEC, } from '../browser-engine-installer.js';
 import { initializeOverlays } from '../../routing/qe-agent-registry.js';
 /**
  * Assets phase - installs skills and agents
@@ -123,6 +123,13 @@ export class AssetsPhase extends BasePhase {
                         // 'already-installed' handled by the pre-flight branch above
                     }
                 }
+                // ADR-091 GAP-05: surface platform diagnostics when the host is one
+                // where Vibium's first-run Chrome auto-download is known to fail.
+                // Today that's just Linux aarch64 at v26.3.x; printed for both
+                // `installed` and `already-installed` results. Non-fatal.
+                if (browserEngine?.platformHint) {
+                    context.services.warn(`  Browser engine platform hint: ${browserEngine.platformHint.message}`);
+                }
             }
             catch (error) {
                 // M9 (devil's-advocate finding): the previous catch re-emitted the
@@ -136,7 +143,7 @@ export class AssetsPhase extends BasePhase {
             }
         }
         else {
-            browserEngine = { status: 'skipped', packageSpec: 'vibium', message: 'minimal mode' };
+            browserEngine = { status: 'skipped', packageSpec: DEFAULT_VIBIUM_SPEC, message: 'minimal mode' };
         }
         // Install n8n platform (optional)
         if (options.withN8n) {