agentic-qe 3.12.0 → 3.12.2

package/dist/cli/chunks/{workflow-ENBWRMBA.js → workflow-GY6SJRQW.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.12.0");process.exit(0)}
-import"./chunk-EZE2HRQB.js";import{b as $}from"./chunk-MBF3Q7FQ.js";import{d as R}from"./chunk-SPEUF7ZL.js";import{b as k,c as C,d as b}from"./chunk-JYX7AZHE.js";import{c as W}from"./chunk-K5SN66B4.js";import"./chunk-7ZIVDGSN.js";import"./chunk-RHC7TFPU.js";import"./chunk-3AFNXU45.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.12.2");process.exit(0)}
+import"./chunk-7KMYBRKJ.js";import{b as $}from"./chunk-MF4FULAI.js";import{d as R}from"./chunk-YSCEUK55.js";import{b as k,c as C,d as b}from"./chunk-4FHJYJCH.js";import{c as W}from"./chunk-CKFZOPZN.js";import"./chunk-EGU54SNK.js";import"./chunk-X47GHZY3.js";import"./chunk-HU6ETNA7.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-UGYJE64S.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-XTKUHTIT.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-UGYJE64S.js"),{writeOutput:u,toJSON:c}=await import("./ci-output-62SGMGB2.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-XTKUHTIT.js"),{writeOutput:u,toJSON:c}=await import("./ci-output-PXBD2QPH.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-IIVV6TCP.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.12.2");process.exit(0)}
+import{a,b,c,d}from"./chunk-GCQATSMK.js";import"./chunk-56MXYSYY.js";import"./chunk-APVXTHTA.js";import"./chunk-AL5QT6OX.js";import"./chunk-YY4KXDI6.js";import"./chunk-R5HC6JVJ.js";import"./chunk-ACDZ2CRV.js";import"./chunk-CKFZOPZN.js";import"./chunk-P65S7AZA.js";import"./chunk-EGU54SNK.js";import"./chunk-X47GHZY3.js";import"./chunk-ZBYMF2QJ.js";import"./chunk-WRMUQVKY.js";import"./chunk-UF3YOGHV.js";import"./chunk-V2QYW5KW.js";import"./chunk-4KEOBDEI.js";import"./chunk-C7VNQ4PY.js";import"./chunk-QYST2TZW.js";import"./chunk-YZ44FUVJ.js";import"./chunk-YDZIPP3Y.js";import"./chunk-CTFW7CMI.js";import"./chunk-HU6ETNA7.js";export{b as DEFAULT_WORKFLOW_CONFIG,a as WorkflowEvents,c as WorkflowOrchestrator,d as createWorkflowOrchestrator};

package/dist/cli/chunks/{wrappers-MHLNYANQ.js → wrappers-MMO5YKOZ.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.12.0");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-ZT2WHCVM.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-ZVPAFX4I.js";import"./chunk-C4SZSPXY.js";import"./chunk-SSXAW3ER.js";import"./chunk-MDT3LIXS.js";import"./chunk-TJEJ4UVX.js";import"./chunk-L5ZLOW3K.js";import"./chunk-K5SN66B4.js";import"./chunk-W2OMW6UU.js";import"./chunk-RHC7TFPU.js";import"./chunk-UVVKFBF7.js";import"./chunk-YKOTOCO6.js";import"./chunk-FZIHOMGY.js";import"./chunk-KJWQ7ENF.js";import"./chunk-V2MD5EDD.js";import"./chunk-64M3FFM4.js";import"./chunk-AEX75YGI.js";import"./chunk-27JCWG5J.js";import"./chunk-2KHDGC7N.js";import"./chunk-3AFNXU45.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.12.2");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-VOHYQ6MX.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-DTXHRALB.js";import"./chunk-APVXTHTA.js";import"./chunk-AL5QT6OX.js";import"./chunk-YY4KXDI6.js";import"./chunk-R5HC6JVJ.js";import"./chunk-ACDZ2CRV.js";import"./chunk-CKFZOPZN.js";import"./chunk-P65S7AZA.js";import"./chunk-X47GHZY3.js";import"./chunk-WRMUQVKY.js";import"./chunk-UF3YOGHV.js";import"./chunk-V2QYW5KW.js";import"./chunk-4KEOBDEI.js";import"./chunk-C7VNQ4PY.js";import"./chunk-QYST2TZW.js";import"./chunk-YZ44FUVJ.js";import"./chunk-YDZIPP3Y.js";import"./chunk-CTFW7CMI.js";import"./chunk-HU6ETNA7.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

@@ -15,7 +15,8 @@ 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 { createParallelEvalRunner, DEFAULT_PARALLEL_EVAL_CONFIG, MockLLMExecutor, } from '../../validation/parallel-eval-runner.js';
+import { resolveEvalExecutor } from '../../validation/provider-llm-executor.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';
@@ -54,6 +55,16 @@ const P2_SKILLS = [
 /**
  * Get skills for a specific tier
  */
+/**
+ * ADR-123: propagate a `--max-budget-usd` flag to the provider layer via the
+ * AQE_MAX_BUDGET_USD env var, which ProviderManager reads as a per-run cap.
+ */
+function applyMaxBudget(maxBudgetUsd) {
+    if (typeof maxBudgetUsd === 'number' && Number.isFinite(maxBudgetUsd) && maxBudgetUsd > 0) {
+        process.env.AQE_MAX_BUDGET_USD = String(maxBudgetUsd);
+        console.log(chalk.gray(`  Budget cap: $${maxBudgetUsd.toFixed(2)} for this run`));
+    }
+}
 function getSkillsByTier(tier) {
     switch (tier) {
         case 3:
@@ -295,6 +306,36 @@ async function handleRunCommand(options) {
         }
         process.exit(result.passed ? 0 : 1);
     }
+    // Issue #557 follow-up: resolve a REAL LLM executor by default. `--mock`
+    // opts into canned responses (offline testing only). If neither a provider
+    // is configured nor --mock is passed, fail loudly rather than fabricate.
+    let executor;
+    let evalManager;
+    if (options.mock) {
+        console.log(chalk.yellow.bold('  ⚠️  MOCK MODE: canned responses, NOT real model output. Results are not valid eval evidence.'));
+        executor = new MockLLMExecutor();
+    }
+    else {
+        const resolved = await resolveEvalExecutor();
+        if (!resolved.executor) {
+            console.error(chalk.red('\n  Cannot run real eval: ') + (resolved.reason ?? 'no provider'));
+            process.exit(1);
+        }
+        executor = resolved.executor;
+        evalManager = resolved.manager;
+        const modeLabel = resolved.billingMode === 'subscription'
+            ? chalk.green('subscription (no per-token charge)')
+            : resolved.billingMode === 'local'
+                ? chalk.green('local (no cost)')
+                : resolved.billingMode === 'metered-capped'
+                    ? chalk.yellow('metered (server-side cap)')
+                    : chalk.red('pay-per-token API');
+        console.log(`  LLM provider: ${chalk.cyan(resolved.providerType)}  billing: ${modeLabel}`);
+        if (process.env.AQE_MAX_BUDGET_USD) {
+            console.log(chalk.gray(`  Budget cap: $${process.env.AQE_MAX_BUDGET_USD} for this run`));
+        }
+        console.log('');
+    }
     const { runner, reasoningBank } = await initializeRunner();
     try {
         // Configure runner
@@ -305,7 +346,7 @@ async function handleRunCommand(options) {
             timeout: options.timeout,
             retryFailedTests: options.retry,
         };
-        const customRunner = createParallelEvalRunner(createSkillValidationLearner(reasoningBank), config);
+        const customRunner = createParallelEvalRunner(createSkillValidationLearner(reasoningBank), config, executor);
         // Set up progress reporting
         if (options.verbose) {
             customRunner.onProgress(displayProgress);
@@ -333,11 +374,30 @@ async function handleRunCommand(options) {
     }
     finally {
         await reasoningBank.dispose();
+        if (evalManager)
+            await evalManager.dispose();
     }
 }
 async function handleRunAllCommand(options) {
     console.log(chalk.bold('\nAQE Parallel Eval Runner - Multi-Skill'));
     console.log(chalk.dim('ADR-056 Phase 5: Worker Pool Pattern\n'));
+    // Issue #557 follow-up: real executor by default; --mock is offline-only.
+    let executor;
+    let evalManager;
+    if (options.mock) {
+        console.log(chalk.yellow.bold('  ⚠️  MOCK MODE: canned responses, NOT real model output. Results are not valid eval evidence.'));
+        executor = new MockLLMExecutor();
+    }
+    else {
+        const resolved = await resolveEvalExecutor();
+        if (!resolved.executor) {
+            console.error(chalk.red('\n  Cannot run real eval: ') + (resolved.reason ?? 'no provider'));
+            process.exit(1);
+        }
+        executor = resolved.executor;
+        evalManager = resolved.manager;
+        console.log(`  LLM provider: ${chalk.cyan(resolved.providerType)}  billing: ${resolved.billingMode}`);
+    }
     const { runner, learner, reasoningBank } = await initializeRunner();
     try {
         // Get skills for tier
@@ -353,7 +413,7 @@ async function handleRunAllCommand(options) {
             ...DEFAULT_PARALLEL_EVAL_CONFIG,
             maxWorkers: options.parallel ? options.workers : 1,
         };
-        const customRunner = createParallelEvalRunner(learner, config);
+        const customRunner = createParallelEvalRunner(learner, config, executor);
         // Run all evals
         const results = await customRunner.runMultipleEvalsParallel(skills, models);
         // Flatten results for display
@@ -394,6 +454,8 @@ async function handleRunAllCommand(options) {
     }
     finally {
         await reasoningBank.dispose();
+        if (evalManager)
+            await evalManager.dispose();
     }
 }
 async function handleStatusCommand(skill) {
@@ -531,7 +593,10 @@ export function createEvalCommand() {
         .option('--no-retry', 'Disable retry of failed tests')
         .option('-o, --output <path>', 'Output file path for results')
         .option('-v, --verbose', 'Show progress during execution', false)
+        .option('--max-budget-usd <n>', 'ADR-123: cap total LLM spend for this run in USD (aborts with COST_LIMIT_EXCEEDED past the cap)', parseFloat)
+        .option('--mock', 'Use canned responses instead of real model calls (offline testing only — results are NOT valid eval evidence)', false)
         .action(async (opts) => {
+        applyMaxBudget(opts.maxBudgetUsd);
         await handleRunCommand({
             skill: opts.skill,
             model: opts.model,
@@ -542,6 +607,7 @@ export function createEvalCommand() {
             retry: opts.retry !== false,
             output: opts.output,
             verbose: opts.verbose,
+            mock: opts.mock === true,
         });
     });
     // Run all evals
@@ -554,7 +620,10 @@ export function createEvalCommand() {
         .option('-w, --workers <n>', 'Number of parallel workers', parseInt, 5)
         .option('-o, --output <path>', 'Output file path for report')
         .option('-v, --verbose', 'Show progress during execution', false)
+        .option('--max-budget-usd <n>', 'ADR-123: cap total LLM spend for this run in USD (aborts with COST_LIMIT_EXCEEDED past the cap)', parseFloat)
+        .option('--mock', 'Use canned responses instead of real model calls (offline testing only — results are NOT valid eval evidence)', false)
         .action(async (opts) => {
+        applyMaxBudget(opts.maxBudgetUsd);
         await handleRunAllCommand({
             skillsTier: opts.skillsTier,
             models: opts.models,
@@ -562,6 +631,7 @@ export function createEvalCommand() {
             workers: opts.workers,
             output: opts.output,
             verbose: opts.verbose,
+            mock: opts.mock === true,
         });
     });
     // Status command

package/dist/cli/commands/llm-router.js

@@ -399,12 +399,14 @@ function formatCost(cost) {
 function getDefaultModelForProvider(provider) {
     const defaults = {
         claude: 'claude-sonnet-4-6',
+        'claude-code': 'sonnet',
         openai: 'gpt-4o',
         ollama: 'llama3.1',
         openrouter: 'anthropic/claude-sonnet-4',
         gemini: 'gemini-2.0-pro',
         'azure-openai': 'gpt-4o',
         bedrock: 'anthropic.claude-sonnet-4-v1:0',
+        cognitum: 'cognitum-auto',
         onnx: 'phi-4',
     };
     return defaults[provider] || '';

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

@@ -22,6 +22,11 @@ export interface DaemonLivenessStatus {
  * tracks a *different*, in-process `QualityDaemon` instance that can't see a
  * truly detached process across separate CLI invocations anyway.
  */
+/**
+ * ADR-123 (issue #557): print how the active LLM provider bills, plus any
+ * configured per-run budget cap. Best-effort — never throws into `aqe health`.
+ */
+export declare function printLlmBilling(): void;
 export declare function checkDaemonLiveness(): DaemonLivenessStatus;
 export declare class StatusHandler implements ICommandHandler {
     readonly name = "status";

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

@@ -9,6 +9,8 @@ import { join } from 'node:path';
 import { getStatusColor, formatUptime, } from './interfaces.js';
 import { writeOutput, toJSON } from '../utils/ci-output.js';
 import { findProjectRoot } from '../../kernel/unified-memory.js';
+import { loadRouterConfig } from '../../shared/llm/router/config-store.js';
+import { billingModeForType } from '../../shared/llm/billing-modes.js';
 /**
  * Check whether the detached background-worker daemon (`.agentic-qe/workers/
  * start-daemon.cjs`, PID recorded in `daemon.pid` — see `10-workers.ts`) is
@@ -19,6 +21,36 @@ import { findProjectRoot } from '../../kernel/unified-memory.js';
  * tracks a *different*, in-process `QualityDaemon` instance that can't see a
  * truly detached process across separate CLI invocations anyway.
  */
+/**
+ * ADR-123 (issue #557): print how the active LLM provider bills, plus any
+ * configured per-run budget cap. Best-effort — never throws into `aqe health`.
+ */
+export function printLlmBilling() {
+    try {
+        const config = loadRouterConfig();
+        const primary = config.defaultProvider;
+        const mode = billingModeForType(primary);
+        const modeLabel = {
+            'metered-api': `${chalk.red('●')} pay-per-token API key (no cap)`,
+            'metered-capped': `${chalk.yellow('●')} pay-per-token with server-side cap`,
+            subscription: `${chalk.green('●')} Claude subscription (no per-token charge)`,
+            local: `${chalk.green('●')} local (no cost)`,
+        };
+        console.log(chalk.blue('\n  LLM Billing:'));
+        console.log(`  Provider: ${chalk.cyan(primary)}  ${modeLabel[mode] ?? mode}`);
+        const cap = Number.parseFloat(process.env.AQE_MAX_BUDGET_USD ?? '');
+        if (Number.isFinite(cap) && cap > 0) {
+            console.log(`  Per-run budget cap: ${chalk.cyan('$' + cap.toFixed(2))}`);
+        }
+        else if (mode === 'metered-api') {
+            console.log(chalk.gray('  No budget cap set — use AQE_MAX_BUDGET_USD or --max-budget-usd.'));
+            console.log(chalk.gray('  Tip: AQE_LLM_PROVIDER=claude-code runs on your Claude subscription.'));
+        }
+    }
+    catch {
+        // Billing display is informational; failures must not break health.
+    }
+}
 export function checkDaemonLiveness() {
     try {
         const pidFile = join(findProjectRoot(), '.agentic-qe', 'workers', 'daemon.pid');
@@ -291,6 +323,9 @@ export class HealthHandler {
                 else {
                     console.log(`  ${chalk.red('\u25CF')} Not running (stale PID: ${daemon.pid ?? 'unknown'}) \u2014 learning/consolidation snapshots will not advance`);
                 }
+                // ADR-123 (issue #557): make LLM billing visible so a paid API key is
+                // never a silent surprise.
+                printLlmBilling();
             }
             console.log('');
             await this.cleanupAndExit(0);

package/dist/coordination/consensus/providers/index.js

@@ -184,6 +184,17 @@ export function registerProvidersFromEnv(enableLogging = false) {
         config.claude = {
             apiKey: process.env.ANTHROPIC_API_KEY,
         };
+        // ADR-123 (issue #557): this consensus/multi-model-verification path bills
+        // the pay-per-token Anthropic API, not a Claude subscription, and has no
+        // budget cap of its own. Surface it so the spend isn't silent. (Full
+        // subscription + budget support for the consensus ModelProvider layer is
+        // tracked as ADR-123 follow-up — it uses a different interface than the
+        // shared LLM ProviderManager.)
+        if ((process.env.AQE_LLM_NO_BILLING_NOTICE ?? '') !== '1') {
+            // eslint-disable-next-line no-console
+            console.error('⚠️  Consensus verification will use the Anthropic API key (pay-per-token, ' +
+                'no budget cap). Unset ANTHROPIC_API_KEY to disable this path.');
+        }
     }
     // Detect OpenAI
     if (process.env.OPENAI_API_KEY) {

package/dist/init/init-wizard-hooks.js

@@ -12,7 +12,7 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, copyFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { safeJsonParse } from '../shared/safe-json.js';
-import { mergeHooksSmart, generateAqeEnvVars, generateV3SettingsSections, } from './settings-merge.js';
+import { mergeHooksSmart, generateAqeEnvVars, generateV3SettingsSections, applyV3Sections, mergeAqeEnv, backupSettingsFile, } from './settings-merge.js';
 // ============================================================================
 // Hook Configuration
 // ============================================================================
@@ -183,31 +183,15 @@ export async function configureHooks(projectRoot, config) {
     // Smart merge: replace old AQE hooks, keep user hooks, add new AQE hooks
     const existingHooks = settings.hooks || {};
     settings.hooks = mergeHooksSmart(existingHooks, aqeHooks);
-    // Set full AQE environment variables
-    const existingEnv = settings.env || {};
-    settings.env = {
-        ...existingEnv,
-        ...generateAqeEnvVars(config),
-    };
-    // Apply v3 settings sections
-    // Permissions are union-merged to preserve user entries (#362)
+    // Add AQE environment variables without clobbering any value the user already
+    // set — including AQE_-prefixed overrides (only missing keys are added).
+    const existingEnv = settings.env;
+    settings.env = mergeAqeEnv(existingEnv, generateAqeEnvVars(config));
+    // Apply v3 settings sections non-destructively: permissions union-merged,
+    // statusLine / includeCoAuthoredBy preserved when user-set, AQE-owned
+    // sections deep-merged so user additions survive (#362 follow-up).
     const v3Sections = generateV3SettingsSections(config, projectRoot);
-    for (const [key, value] of Object.entries(v3Sections)) {
-        if (key === '_aqePermissions') {
-            // Union-merge: add AQE entries without removing user-added permissions
-            const existingPerms = settings.permissions || {};
-            const existingAllow = existingPerms.allow || [];
-            const aqeEntries = value;
-            const merged = [...new Set([...existingAllow, ...aqeEntries])];
-            settings.permissions = {
-                ...existingPerms,
-                allow: merged,
-            };
-        }
-        else {
-            settings[key] = value;
-        }
-    }
+    applyV3Sections(settings, v3Sections);
     // Enable MCP servers (deduplicate, replace old 'aqe' with 'agentic-qe')
     let existingMcp = settings.enabledMcpjsonServers || [];
     existingMcp = existingMcp.filter(s => s !== 'aqe');
@@ -215,6 +199,8 @@ export async function configureHooks(projectRoot, config) {
         existingMcp.push('agentic-qe');
     }
     settings.enabledMcpjsonServers = existingMcp;
+    // Back up the pristine original settings.json before writing (like CLAUDE.md)
+    backupSettingsFile(settingsPath);
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
     // Install cross-phase memory hooks configuration
     await installCrossPhaseMemoryHooks(projectRoot);

package/dist/init/phases/07-hooks.js

@@ -13,7 +13,7 @@ import { fileURLToPath } from 'url';
 import { safeJsonParse } from '../../shared/safe-json.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-import { isAqeHookEntry, mergeHooksSmart, generateAqeEnvVars, generateV3SettingsSections, } from '../settings-merge.js';
+import { isAqeHookEntry, mergeHooksSmart, generateAqeEnvVars, generateV3SettingsSections, applyV3Sections, mergeAqeEnv, backupSettingsFile, } from '../settings-merge.js';
 import { BasePhase, } from './phase-interface.js';
 /**
  * Hooks phase - configures Claude Code hooks
@@ -76,31 +76,16 @@ export class HooksPhase extends BasePhase {
         }
         // Smart merge: remove old AQE hooks, keep user hooks, add new AQE hooks
         settings.hooks = mergeHooksSmart(existingHooks, aqeHooks);
-        // Set full AQE environment variables
-        const existingEnv = settings.env || {};
-        settings.env = {
-            ...existingEnv,
-            ...generateAqeEnvVars(config),
-        };
-        // Apply v3 settings sections (statusLine, v3Configuration, v3Learning, etc.)
-        // Permissions are union-merged to preserve user entries (#362)
+        // Add AQE environment variables without clobbering any value the user
+        // already set — including AQE_-prefixed overrides (only missing keys added).
+        const existingEnv = settings.env;
+        settings.env = mergeAqeEnv(existingEnv, generateAqeEnvVars(config));
+        // Apply v3 settings sections non-destructively:
+        //  - permissions union-merged (preserve user entries, #362)
+        //  - statusLine / includeCoAuthoredBy preserved when user-set (#362 follow-up)
+        //  - AQE-owned sections deep-merged so user additions survive
         const v3Sections = generateV3SettingsSections(config, projectRoot);
-        for (const [key, value] of Object.entries(v3Sections)) {
-            if (key === '_aqePermissions') {
-                // Union-merge: add AQE entries without removing user-added permissions
-                const existingPerms = settings.permissions || {};
-                const existingAllow = existingPerms.allow || [];
-                const aqeEntries = value;
-                const merged = [...new Set([...existingAllow, ...aqeEntries])];
-                settings.permissions = {
-                    ...existingPerms,
-                    allow: merged,
-                };
-            }
-            else {
-                settings[key] = value;
-            }
-        }
+        applyV3Sections(settings, v3Sections);
         // Enable MCP servers (deduplicate, replace old 'aqe' with 'agentic-qe')
         let existingMcp = settings.enabledMcpjsonServers || [];
         // Remove legacy 'aqe' entry if present (renamed to 'agentic-qe')
@@ -109,6 +94,11 @@ export class HooksPhase extends BasePhase {
             existingMcp.push('agentic-qe');
         }
         settings.enabledMcpjsonServers = existingMcp;
+        // Back up the pristine original settings.json before writing (like CLAUDE.md)
+        const backupPath = backupSettingsFile(settingsPath);
+        if (backupPath) {
+            context.services.log(`  Backup created: ${backupPath}`);
+        }
         // Write settings
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
         // Write README and install hook assets (bridge script, cross-phase memory)

package/dist/init/settings-merge.d.ts

@@ -8,6 +8,18 @@
  * - Generates full env vars and v3 settings sections
  */
 import type { AQEInitConfig } from './types.js';
+/**
+ * Create a one-time `.backup` of an existing settings.json before AQE modifies
+ * it — mirroring the CLAUDE.md backup convention.
+ *
+ * The backup captures the pristine, pre-AQE file and is NOT overwritten on
+ * subsequent re-inits, so the user's original settings are always recoverable.
+ * No-op when the file does not exist yet (fresh install) or a backup already
+ * exists. Failures are swallowed — a backup problem must never block init.
+ *
+ * @returns the backup path when a backup was written, otherwise null.
+ */
+export declare function backupSettingsFile(settingsPath: string): string | null;
 /**
  * Check if a single hook entry belongs to AQE (any variant).
  * Matches commands containing 'aqe' or 'agentic-qe' in any form.
@@ -23,10 +35,42 @@ export declare function isAqeHookEntry(entry: unknown): boolean;
  * 3. Preserve any hook types not in the new config
  */
 export declare function mergeHooksSmart(existingHooks: Record<string, unknown[]>, newAqeHooks: Record<string, unknown[]>): Record<string, unknown[]>;
+/**
+ * Merge AQE's environment variables into a user's existing `env` block WITHOUT
+ * clobbering values the user already set — including AQE_-prefixed ones.
+ *
+ * Re-running `aqe init` fills in any missing AQE env vars but leaves every
+ * existing value untouched, so a user who intentionally flipped, say,
+ * `AQE_LEARNING_ENABLED=false` keeps their choice. Non-AQE env vars are always
+ * preserved. Returns a new object; inputs are not mutated.
+ */
+export declare function mergeAqeEnv(existingEnv: Record<string, string> | undefined, aqeEnv: Record<string, string>): Record<string, string>;
 /**
  * Generate the full set of AQE environment variables for settings.json.
  */
 export declare function generateAqeEnvVars(config: AQEInitConfig): Record<string, string>;
+/**
+ * Detect whether a `statusLine` block is one AQE generated (vs. a user's own).
+ * AQE's status line invokes the statusline-v3.cjs helper (or falls back to the
+ * "Agentic QE v3" banner). Anything else is treated as user-owned and preserved.
+ */
+export declare function isAqeStatusLine(statusLine: unknown): boolean;
+/**
+ * Apply the generated v3 settings sections onto an existing settings object
+ * WITHOUT clobbering configuration the user already set:
+ *
+ * - `_aqePermissions`: union-merge into `permissions.allow`, preserving the
+ *   user's existing allow/deny entries (#362).
+ * - `statusLine`: generic Claude Code setting — only written when absent or when
+ *   the existing one is AQE's own (so a user's custom status line is preserved).
+ * - `includeCoAuthoredBy`: generic Claude Code setting — only written when the
+ *   user has not set it explicitly (respects an intentional `false`).
+ * - `aqe` / `v3Configuration` / `v3Learning`: AQE-owned sections, deep-merged so
+ *   AQE values are refreshed while any user-added keys survive.
+ *
+ * Mutates and returns `settings`.
+ */
+export declare function applyV3Sections(settings: Record<string, unknown>, sections: Record<string, unknown>): Record<string, unknown>;
 /**
  * Generate v3-specific settings sections for settings.json.
  * These sections enable the self-learning system, status line, and permissions.

package/dist/init/settings-merge.js

@@ -7,16 +7,49 @@
  * - Preserves non-AQE hooks from the user's config
  * - Generates full env vars and v3 settings sections
  */
-// Patterns that identify a hook command as belonging to AQE
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+/**
+ * Create a one-time `.backup` of an existing settings.json before AQE modifies
+ * it — mirroring the CLAUDE.md backup convention.
+ *
+ * The backup captures the pristine, pre-AQE file and is NOT overwritten on
+ * subsequent re-inits, so the user's original settings are always recoverable.
+ * No-op when the file does not exist yet (fresh install) or a backup already
+ * exists. Failures are swallowed — a backup problem must never block init.
+ *
+ * @returns the backup path when a backup was written, otherwise null.
+ */
+export function backupSettingsFile(settingsPath) {
+    if (!existsSync(settingsPath))
+        return null;
+    const backupPath = `${settingsPath}.backup`;
+    if (existsSync(backupPath))
+        return null; // keep the pristine original
+    try {
+        writeFileSync(backupPath, readFileSync(settingsPath, 'utf-8'), 'utf-8');
+        return backupPath;
+    }
+    catch {
+        return null;
+    }
+}
+// Patterns that identify a hook command as belonging to AQE.
+//
+// These MUST be specific to AQE's own hooks. They must NOT match hooks that
+// other tools install (e.g. ruflo / claude-flow), otherwise re-running
+// `aqe init` in a project that already ran `ruflo init` would strip the user's
+// ruflo hooks. In particular:
+//   - do NOT match on `.claude/helpers/` broadly — ruflo's hook-handler.cjs and
+//     auto-memory-hook.mjs live there too (match AQE's own helpers by name)
+//   - do NOT match on `ruflo` — those are the user's hooks, preserve them
 const AQE_COMMAND_PATTERNS = [
     /\baqe\b/i,
     /\bagentic-qe\b/i,
     /\bnpx\s+agentic-qe\b/i,
     /\bnpx\s+@anthropics\/agentic-qe\b/i,
+    /aqe-hook\.cjs/i,
     /brain-checkpoint\.cjs/i,
-    /\.claude\/helpers\//i,
-    /\bruflo\b/i,
-    /dist\/cli\/bundle\.js/i,
+    /statusline-v3\.cjs/i,
 ];
 /**
  * Check if a single hook entry belongs to AQE (any variant).
@@ -62,6 +95,19 @@ export function mergeHooksSmart(existingHooks, newAqeHooks) {
     }
     return merged;
 }
+/**
+ * Merge AQE's environment variables into a user's existing `env` block WITHOUT
+ * clobbering values the user already set — including AQE_-prefixed ones.
+ *
+ * Re-running `aqe init` fills in any missing AQE env vars but leaves every
+ * existing value untouched, so a user who intentionally flipped, say,
+ * `AQE_LEARNING_ENABLED=false` keeps their choice. Non-AQE env vars are always
+ * preserved. Returns a new object; inputs are not mutated.
+ */
+export function mergeAqeEnv(existingEnv, aqeEnv) {
+    // AQE defaults first, then existing values win on any key collision.
+    return { ...aqeEnv, ...(existingEnv || {}) };
+}
 /**
  * Generate the full set of AQE environment variables for settings.json.
  */
@@ -85,6 +131,75 @@ export function generateAqeEnvVars(config) {
         AQE_V3_SUCCESS_RATE_THRESHOLD: String(config.learning?.qualityThreshold ?? 0.7),
     };
 }
+/**
+ * Detect whether a `statusLine` block is one AQE generated (vs. a user's own).
+ * AQE's status line invokes the statusline-v3.cjs helper (or falls back to the
+ * "Agentic QE v3" banner). Anything else is treated as user-owned and preserved.
+ */
+export function isAqeStatusLine(statusLine) {
+    const cmd = statusLine?.command;
+    return typeof cmd === 'string' && /statusline-v3\.cjs|Agentic QE v3/.test(cmd);
+}
+/**
+ * Deep-merge `source` (AQE-owned values) onto `target` (whatever the user has):
+ * plain-object subtrees merge recursively so a user's extra keys survive, while
+ * AQE's values win on conflicting leaves. Arrays and primitives are replaced by
+ * the AQE value (these sections are AQE-managed).
+ */
+function deepMergeOwned(target, source) {
+    if (!isPlainObject(target) || !isPlainObject(source))
+        return source;
+    const out = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        out[key] = deepMergeOwned(out[key], value);
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Apply the generated v3 settings sections onto an existing settings object
+ * WITHOUT clobbering configuration the user already set:
+ *
+ * - `_aqePermissions`: union-merge into `permissions.allow`, preserving the
+ *   user's existing allow/deny entries (#362).
+ * - `statusLine`: generic Claude Code setting — only written when absent or when
+ *   the existing one is AQE's own (so a user's custom status line is preserved).
+ * - `includeCoAuthoredBy`: generic Claude Code setting — only written when the
+ *   user has not set it explicitly (respects an intentional `false`).
+ * - `aqe` / `v3Configuration` / `v3Learning`: AQE-owned sections, deep-merged so
+ *   AQE values are refreshed while any user-added keys survive.
+ *
+ * Mutates and returns `settings`.
+ */
+export function applyV3Sections(settings, sections) {
+    for (const [key, value] of Object.entries(sections)) {
+        if (key === '_aqePermissions') {
+            const existingPerms = settings.permissions || {};
+            const existingAllow = existingPerms.allow || [];
+            const merged = [...new Set([...existingAllow, ...value])];
+            settings.permissions = { ...existingPerms, allow: merged };
+        }
+        else if (key === 'statusLine') {
+            // Preserve a user's (or another tool's) custom status line.
+            if (settings.statusLine === undefined || isAqeStatusLine(settings.statusLine)) {
+                settings.statusLine = value;
+            }
+        }
+        else if (key === 'includeCoAuthoredBy') {
+            // Respect an explicit user choice; only set the default when unset.
+            if (settings.includeCoAuthoredBy === undefined) {
+                settings.includeCoAuthoredBy = value;
+            }
+        }
+        else {
+            // AQE-owned section — deep-merge so user additions are not dropped.
+            settings[key] = deepMergeOwned(settings[key], value);
+        }
+    }
+    return settings;
+}
 /**
  * Generate v3-specific settings sections for settings.json.
  * These sections enable the self-learning system, status line, and permissions.