agentic-qe 3.13.0 → 3.13.1

package/dist/mcp/handlers/domain-handler-configs.js

@@ -108,6 +108,9 @@ export const testGenerateConfig = {
         const domainTests = data.tests;
         const hasRealTests = Array.isArray(domainTests) && domainTests.length > 0
             && domainTests[0].testCode;
+        // #567: did the ADR-051 LLM branch actually run? Report it instead of
+        // asserting `aiGenerated: true` unconditionally.
+        const llmEnhanced = data.llmEnhanced === true;
         const tests = hasRealTests
             ? domainTests.map((t, i) => ({
                 id: generateTestId(),
@@ -119,7 +122,7 @@ export const testGenerateConfig = {
                     : [`test assertion ${i}`],
                 expectedResult: null,
                 estimatedDuration: t.type === 'integration' ? 2000 : 1000,
-                aiGenerated: true,
+                aiGenerated: llmEnhanced,
                 testCode: t.testCode,
                 sourceFile: t.sourceFile,
                 testFile: t.testFile || t.file,
@@ -133,7 +136,9 @@ export const testGenerateConfig = {
             aiInsights,
             coverage: {
                 predicted: data.coverageEstimate || params?.coverageGoal || 80,
-                confidence: 0.9,
+                // #567: a template scaffold's coverage prediction is a guess, not a
+                // 0.9-confidence estimate. Don't dress it up as one.
+                confidence: llmEnhanced ? 0.9 : 0.3,
                 achievable: true,
             },
             properties: tests.filter(t => t.type === 'property').map(t => ({
@@ -151,6 +156,10 @@ export const testGenerateConfig = {
             patternsUsed: data.patternsUsed || ['assertion-patterns', 'mock-generation', 'edge-case-detection'],
             duration,
             savedFiles,
+            // #567: propagate the LLM-enhancement signal to the MCP caller.
+            llmEnhanced,
+            ...(data.generationMode ? { generationMode: data.generationMode } : {}),
+            ...(data.note ? { note: data.note } : {}),
         };
     },
 };
@@ -253,12 +262,40 @@ export const coverageAnalyzeConfig = {
         // The domain returns CoverageReport { summary: { line, branch, function, statement, files }, ... }
         // Map from both nested (domain) and flat (legacy) field shapes.
         const summary = data.summary;
-        const lineCoverage = summary?.line ?? data.lineCoverage ?? 0;
-        const branchCoverage = summary?.branch ?? data.branchCoverage ?? 0;
-        const functionCoverage = summary?.function ?? data.functionCoverage ?? 0;
-        const statementCoverage = summary?.statement ?? data.statementCoverage ?? lineCoverage;
         const totalFiles = summary?.files ?? data.totalFiles ?? 0;
         const gaps = data.gaps || [];
+        // #569/ADR-126: an ABSENT provenance flag means "unknown", never "collected".
+        //
+        // Defaulting these to `true` (`!== false`) meant any producer that supplies
+        // no provenance at all — notably the coverage-analysis domain plugin, whose
+        // handler returns a nested-`summary` CoverageReport — surfaced the exact
+        // impossible pair from the issue: 100% branch coverage alongside 0% function
+        // coverage, labelled `measured: true` with `confidence: 0.7` on its gaps.
+        // Requiring an explicit `true` makes an unprovenanced result honest (`null`)
+        // instead of confidently wrong.
+        const branchDataCollected = data.branchDataCollected === true;
+        const functionDataCollected = data.functionDataCollected === true;
+        const branchCoverage = branchDataCollected
+            ? (summary?.branch ?? data.branchCoverage ?? null)
+            : null;
+        const functionCoverage = functionDataCollected
+            ? (summary?.function ?? data.functionCoverage ?? null)
+            : null;
+        // #569: is this a measurement or a static estimate? Everything downstream —
+        // gap confidence, AI insights, risk assessment — must be qualified by it.
+        const estimated = data.estimated === true;
+        // #569/ADR-126: `measured` is NOT the complement of `estimated` — there is a
+        // third state where nothing was collected at all. Deriving it as `!estimated`
+        // reported an empty project (no sources, no coverage report, nothing run) as
+        // `lineCoverage: 0, measured: true` — "we measured 0%" when the truth is "we
+        // measured nothing". Trust only an explicit claim from the producer.
+        const measured = data.measured === true;
+        // Likewise, a `null` line/statement figure must survive as `null`. `?? 0`
+        // turns "no data" into a plottable 0%.
+        const rawLine = summary?.line ?? data.lineCoverage;
+        const lineCoverage = rawLine ?? null;
+        const rawStatement = summary?.statement ?? data.statementCoverage;
+        const statementCoverage = rawStatement ?? lineCoverage;
         const learning = generateV2LearningFeedback('coverage-analyzer');
         // Map gap analysis from real data — never fabricate file paths
         const detailedGaps = gaps.map((gap, i) => {
@@ -278,7 +315,12 @@ export const coverageAnalyzeConfig = {
                 suggestion: g.suggestedTest || 'Add test coverage',
                 suggestedTest: g.suggestedTest || 'Add test coverage',
                 riskScore: g.riskScore || 0.5,
-                confidence: g.confidence || 0.7,
+                // #569: the 0.7 default confidence is only defensible for a gap derived
+                // from a real measurement. An estimated gap carries its own low
+                // confidence from the handler; a gap with no provenance at all is not
+                // known to be measured either, so it gets the cautious value too.
+                confidence: g.confidence ?? (measured ? 0.7 : 0.2),
+                estimated: g.estimated === true || estimated,
             };
         }).filter((g) => g !== null);
         // Use real file data from the analyzer if available, never fabricate file paths
@@ -287,8 +329,9 @@ export const coverageAnalyzeConfig = {
             ? coverageByFileData.map(f => ({
                 file: f.file,
                 lineCoverage: f.lineCoverage || 0,
-                branchCoverage: f.branchCoverage || 0,
-                functionCoverage: f.functionCoverage || 0,
+                // #569: preserve null (metric not collected) instead of collapsing to 0.
+                branchCoverage: f.branchCoverage ?? null,
+                functionCoverage: f.functionCoverage ?? null,
             }))
             : [];
         return {
@@ -305,11 +348,25 @@ export const coverageAnalyzeConfig = {
                 weeklyChange: 0,
             },
             aiInsights: totalFiles > 0 ? {
-                recommendations: data.recommendations || [
-                    'Run tests with coverage enabled to get accurate metrics',
-                ],
-                riskAssessment: lineCoverage < 70 ? 'high' : lineCoverage < 85 ? 'medium' : 'low',
-                confidence: 0.88,
+                recommendations: estimated
+                    // #569: the reported insights ("Coverage is 15.9% below threshold",
+                    // "Function coverage is below 70%") were all derived from estimated
+                    // numbers and presented as findings. Lead with the caveat.
+                    ? [
+                        'ESTIMATED RESULT — no instrumentation ran. The figures below are a ' +
+                            'static guess from source shape, not measured coverage. Do not act on ' +
+                            'individual gaps without running real instrumentation first.',
+                        ...(data.recommendations || []),
+                    ]
+                    : (data.recommendations || [
+                        'Run tests with coverage enabled to get accurate metrics',
+                    ]),
+                // #569: risk can only be graded off a real number. `null < 70` is
+                // `false` in JS, which would have silently graded "no data" as 'low'.
+                riskAssessment: (estimated || !measured || lineCoverage === null)
+                    ? 'unknown'
+                    : (lineCoverage < 70 ? 'high' : lineCoverage < 85 ? 'medium' : 'low'),
+                confidence: estimated ? 0.2 : (measured ? 0.88 : 0),
             } : {
                 recommendations: [
                     'No coverage data found. Run tests with coverage first (e.g., npm test -- --coverage, or pytest --cov)',
@@ -329,6 +386,14 @@ export const coverageAnalyzeConfig = {
             gaps: detailedGaps,
             duration,
             savedFiles,
+            // #569: provenance travels with the numbers so a caller can never mistake
+            // a static estimate for a measurement.
+            estimated,
+            measured,
+            coverageMethod: data.coverageMethod ?? 'unknown',
+            branchDataCollected,
+            functionDataCollected,
+            ...(data.warning ? { warning: data.warning } : {}),
         };
     },
 };

package/dist/mcp/types.d.ts

@@ -446,6 +446,15 @@ export interface TestGenerateResult {
     suggestions?: string[];
     savedFiles?: string[];
     patternsUsed?: string[];
+    /**
+     * #567: true when the ADR-051 LLM branch actually ran. When false the tests
+     * are deterministic template scaffolding — see `generationMode`/`note`.
+     */
+    llmEnhanced?: boolean;
+    /** #567: set to 'deterministic-template' when no LLM enhancement was applied. */
+    generationMode?: string;
+    /** #567: human-readable reason the LLM branch did not run. */
+    note?: string;
     tests?: unknown[];
     antiPatterns?: unknown[];
     aiInsights?: Record<string, unknown>;
@@ -462,19 +471,46 @@ export interface CoverageAnalyzeResult {
     taskId: string;
     status: string;
     duration: number;
-    lineCoverage: number;
-    branchCoverage: number;
-    functionCoverage: number;
+    /**
+     * #569: `null` when no coverage figure was produced at all (no report, no
+     * instrumentation run, nothing to estimate from). `0` means a measured zero;
+     * `null` means "we don't know" — the two must not be conflated.
+     */
+    lineCoverage: number | null;
+    /**
+     * #569: `null` when branch data was not collected. Never report a branch
+     * percentage — least of all 100% — that no instrumentation produced.
+     */
+    branchCoverage: number | null;
+    /** #569: `null` when function-level data was not collected. */
+    functionCoverage: number | null;
     gaps?: CoverageGap[];
     riskScore?: number;
     savedFiles?: string[];
-    statementCoverage?: number;
+    /** #569: `null` when no figure was produced — see `lineCoverage`. */
+    statementCoverage?: number | null;
     totalFiles?: number;
     coverageByFile?: unknown[];
     gapAnalysis?: Record<string, unknown>;
     trends?: Record<string, unknown>;
     aiInsights?: Record<string, unknown>;
     learning?: Record<string, unknown>;
+    /**
+     * #569 provenance. `true` means the figures are a STATIC ESTIMATE derived
+     * from source shape, not measured coverage. Callers must not present an
+     * estimated result as a measurement.
+     */
+    estimated?: boolean;
+    /** Inverse of `estimated`: real instrumentation produced these numbers. */
+    measured?: boolean;
+    /** How the numbers were obtained: instrumented-report | cargo-llvm-cov | static-estimation | none. */
+    coverageMethod?: string;
+    /** Whether branch data was actually collected. */
+    branchDataCollected?: boolean;
+    /** Whether function-level data was actually collected. */
+    functionDataCollected?: boolean;
+    /** Caveats the caller should surface (e.g. "no instrumentation ran"). */
+    warning?: string;
 }
 /**
  * Coverage gap
@@ -492,6 +528,8 @@ export interface CoverageGap {
     priority?: string;
     suggestedTest?: string;
     riskScore?: number;
+    /** #569: true when this gap came from a static estimate, not a measurement. */
+    estimated?: boolean;
 }
 /**
  * Memory store result

package/dist/optimization/session-cache.d.ts

@@ -47,8 +47,20 @@ export declare class SessionOperationCache {
     private misses;
     constructor(config?: Partial<SessionCacheConfig>);
     /**
-     * Compute a deterministic fingerprint from domain + action + input.
+     * Compute a deterministic fingerprint from build + domain + action + input.
      * Uses SHA-256 of the canonicalized JSON (recursively sorted keys), truncated to 16 hex chars.
+     *
+     * The build identity is part of the key on purpose. Entries are persisted to
+     * `kv_store` and survive process restarts *and package upgrades*, so a
+     * fingerprint over inputs alone means an upgraded install keeps replaying the
+     * previous version's answers until the TTL lapses — the fix looks like it did
+     * not work. That is exactly what happened while verifying issue #569: a
+     * project analyzed before the fix kept returning the old fabricated coverage
+     * numbers (`lineCoverage: 0, measured: true`) from cache, while an untouched
+     * project returned the corrected result.
+     *
+     * Including the version means an upgrade misses cleanly rather than serving
+     * stale answers; entries from the old build simply age out.
      */
     computeFingerprint(domain: string, action: string, input: Record<string, unknown>): string;
     /**

package/dist/optimization/session-cache.js

@@ -13,6 +13,19 @@
  * - TTL-based expiry, LRU-ish eviction at capacity
  */
 import { createHash } from 'crypto';
+/**
+ * Build identity mixed into every cache fingerprint so persisted entries never
+ * outlive the code that produced them. `__CLI_VERSION__` is substituted at bundle
+ * time; in source/test runs it is undefined and we fall back to a dev marker.
+ *
+ * `AQE_SESSION_CACHE_SALT` lets an operator force a cold cache without deleting
+ * anything (e.g. after a local rebuild that keeps the same version string).
+ */
+function getBuildIdentity() {
+    const version = typeof __CLI_VERSION__ !== 'undefined' ? __CLI_VERSION__ : 'dev';
+    const salt = (process.env.AQE_SESSION_CACHE_SALT ?? '').trim();
+    return salt ? `${version}+${salt}` : version;
+}
 export const DEFAULT_SESSION_CACHE_CONFIG = {
     enabled: true,
     maxEntries: 500,
@@ -51,11 +64,23 @@ export class SessionOperationCache {
         this.config = { ...DEFAULT_SESSION_CACHE_CONFIG, ...config };
     }
     /**
-     * Compute a deterministic fingerprint from domain + action + input.
+     * Compute a deterministic fingerprint from build + domain + action + input.
      * Uses SHA-256 of the canonicalized JSON (recursively sorted keys), truncated to 16 hex chars.
+     *
+     * The build identity is part of the key on purpose. Entries are persisted to
+     * `kv_store` and survive process restarts *and package upgrades*, so a
+     * fingerprint over inputs alone means an upgraded install keeps replaying the
+     * previous version's answers until the TTL lapses — the fix looks like it did
+     * not work. That is exactly what happened while verifying issue #569: a
+     * project analyzed before the fix kept returning the old fabricated coverage
+     * numbers (`lineCoverage: 0, measured: true`) from cache, while an untouched
+     * project returned the corrected result.
+     *
+     * Including the version means an upgrade misses cleanly rather than serving
+     * stale answers; entries from the old build simply age out.
      */
     computeFingerprint(domain, action, input) {
-        const canonical = canonicalStringify({ action, domain, input });
+        const canonical = canonicalStringify({ action, build: getBuildIdentity(), domain, input });
         return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
     }
     /**

package/dist/shared/llm/llm-router-service.js

@@ -22,6 +22,47 @@
 import { ProviderManager } from './provider-manager.js';
 import { HybridRouter } from './router/hybrid-router.js';
 import { loadRouterConfig, shouldEnableRouter, detectAvailableProvidersFromEnv, } from './router/config-store.js';
+import { setAgentProviderOverrides, createOverrideRoutingRules, } from './router/agent-router-config.js';
+import { DEFAULT_QE_ROUTING_RULES } from './router/routing-rules.js';
+import { createLogger } from '../../logging/logger-factory.js';
+const routerServiceLogger = createLogger('llm/router-service');
+/**
+ * Issue #568: make `.agentic-qe/llm-config.json`'s `agentOverrides` map actually
+ * take effect.
+ *
+ * Two steps, and both are needed:
+ *   1. install the map so `getPreferredModelForAgent()` consults it, and
+ *   2. materialize a routing rule per overridden agent and put it *ahead* of the
+ *      rules the router would otherwise evaluate.
+ *
+ * Step 2 is the part that was missing before: `HybridRouter` only ever evaluates
+ * `config.rules` (falling back to `DEFAULT_QE_ROUTING_RULES`), and the generated
+ * per-agent ruleset was never installed into either — which is why the whole
+ * `agent-router-config` mechanism was unreachable from outside a single call
+ * stack.
+ *
+ * No overrides on disk => returns the config untouched.
+ */
+function applyAgentOverrides(config) {
+    // Pass each provider's own default model so a `{ "provider": "ollama" }`
+    // override resolves to a model ollama can serve, not the Claude model id the
+    // agent's category default happened to carry.
+    const providerDefaultModels = {};
+    for (const [provider, cfg] of Object.entries(config.providers ?? {})) {
+        if (cfg?.defaultModel) {
+            providerDefaultModels[provider] = cfg.defaultModel;
+        }
+    }
+    setAgentProviderOverrides(config.agentOverrides, providerDefaultModels);
+    const overrideRules = createOverrideRoutingRules();
+    if (overrideRules.length === 0) {
+        return config;
+    }
+    // Mirror HybridRouter's own fallback so materializing overrides never has the
+    // side effect of dropping the default QE rules.
+    const baseRules = config.rules.length > 0 ? config.rules : DEFAULT_QE_ROUTING_RULES;
+    return { ...config, rules: [...overrideRules, ...baseRules] };
+}
 /**
  * Order in which we pick fallbacks when the user hasn't specified any.
  * Local-first (free), then cheapest cloud, then richer providers. This
@@ -46,11 +87,11 @@ const FALLBACK_PRIORITY = [
 export async function createLLMRouterService(options = {}) {
     // Honor the test-injected ProviderManager path first.
     if (options.providerManager) {
-        const config = loadRouterConfig({
+        const config = applyAgentOverrides(loadRouterConfig({
             projectRoot: options.projectRoot,
             override: options.override,
             env: options.env,
-        });
+        }));
         const router = new HybridRouter(options.providerManager, config);
         await router.initialize();
         return {
@@ -63,15 +104,29 @@ export async function createLLMRouterService(options = {}) {
     if (!shouldEnableRouter({ projectRoot: options.projectRoot, env: options.env })) {
         return null;
     }
-    const config = loadRouterConfig({
+    const config = applyAgentOverrides(loadRouterConfig({
         projectRoot: options.projectRoot,
         override: options.override,
         env: options.env,
-    });
+    }));
     const enabled = pickEnabledProviders(config, options.env ?? process.env);
     if (enabled.length === 0) {
         return null;
     }
+    // Issue #568: an override naming a provider that isn't enabled would silently
+    // fall through to the default chain — the exact "configured it and nothing
+    // happened" failure this feature exists to avoid. Say so out loud. We do NOT
+    // auto-enable it: that would opt the user into a provider (and possibly paid
+    // billing) they never turned on.
+    const enabledSet = new Set(enabled);
+    for (const [agentType, override] of Object.entries(config.agentOverrides ?? {})) {
+        if (override.provider && !enabledSet.has(override.provider)) {
+            routerServiceLogger.warn(`[llm-config] agentOverrides["${agentType}"] routes to provider ` +
+                `"${override.provider}", which is not enabled (no API key detected and not ` +
+                `enabled in .agentic-qe/llm-config.json). This override will not take effect ` +
+                `until that provider is available.`);
+        }
+    }
     const { primary, fallbacks } = pickPrimaryAndFallbacks(config, enabled);
     const providerManagerConfig = {
         primary: primary,

package/dist/shared/llm/router/agent-router-config.d.ts

@@ -8,7 +8,7 @@
  * - Override mechanism for specific tasks
  * - Agent category detection and preferred model resolution
  */
-import { ExtendedProviderType, RoutingRule, TaskComplexity } from './types';
+import { ExtendedProviderType, RoutingRule, TaskComplexity, AgentProviderOverride } from './types';
 /**
  * Agent categories for routing decisions
  */
@@ -120,7 +120,34 @@ export declare const DEFAULT_CATEGORY_CAPABILITIES: Record<AgentCategory, AgentC
  */
 export declare function getAgentRoutingCategory(agentType: string): AgentCategory;
 /**
- * Get the preferred model for an agent type
+ * Install the on-disk per-agent overrides (issue #568). Called by the router
+ * service after `loadRouterConfig()` has validated them.
+ *
+ * Replaces the whole map rather than merging, so reloading a config that
+ * removed an entry actually removes it.
+ *
+ * @param overrides validated `agentOverrides` map
+ * @param defaultModels per-provider default model ids, so a provider-only
+ *   override resolves to a model that provider can actually serve
+ */
+export declare function setAgentProviderOverrides(overrides: Record<string, AgentProviderOverride> | undefined, defaultModels?: Partial<Record<ExtendedProviderType, string>>): void;
+/** Current on-disk per-agent overrides. Primarily for diagnostics and tests. */
+export declare function getAgentProviderOverrides(): Readonly<Record<string, AgentProviderOverride>>;
+/** Clear installed overrides. For tests. */
+export declare function resetAgentProviderOverrides(): void;
+/**
+ * Get the preferred model for an agent type.
+ *
+ * Resolution order (issue #568):
+ *   1. `agentOverrides[agentType]` from `.agentic-qe/llm-config.json` — the
+ *      user's explicit, hand-written intent, so it wins.
+ *   2. the agent's category default (`AGENT_CATEGORY_MAP` ->
+ *      `DEFAULT_CATEGORY_MODELS`).
+ *
+ * An override is a *partial*: fields it does not set keep their category
+ * default, so `{ "provider": "ollama" }` re-provisions the provider without
+ * forcing the user to also restate temperature, token budget, and priority.
+ *
  * @param agentType - The agent type identifier
  * @returns The model preference configuration
  */
@@ -161,6 +188,23 @@ export declare function isLatencySensitive(agentType: string): boolean;
  * @returns A routing rule for this agent type
  */
 export declare function createAgentRoutingRule(agentType: string): RoutingRule;
+/**
+ * Build routing rules for exactly the agent types the user overrode on disk
+ * (issue #568).
+ *
+ * Why a separate builder rather than `createAgentRoutingRule`: that one also
+ * constrains on `requiresReasoning`, which is right for the generated
+ * whole-roster ruleset but wrong here — a user who wrote
+ * `"qe-mutation-tester": { "provider": "ollama" }` means *always*, not "only when
+ * the request happens to be flagged as needing reasoning". These rules match on
+ * agent type alone.
+ *
+ * Returns `[]` when nothing is overridden, so a project without the key gets the
+ * exact rule set it got before.
+ *
+ * @returns Routing rules, highest priority first
+ */
+export declare function createOverrideRoutingRules(): RoutingRule[];
 /**
  * Create routing rules for all agents in a category
  * @param category - The agent category

package/dist/shared/llm/router/agent-router-config.js

@@ -324,14 +324,97 @@ export function getAgentRoutingCategory(agentType) {
     }
     return 'general';
 }
+// ============================================================================
+// On-disk per-agent overrides (issue #568)
+// ============================================================================
+/**
+ * Per-agent-type overrides sourced from `.agentic-qe/llm-config.json`'s
+ * `agentOverrides` key.
+ *
+ * Module-level state, deliberately: `getPreferredModelForAgent` is a synchronous
+ * pure-lookup function called from many places (rule construction, capability
+ * resolution, the router's own dispatch), and threading a config object through
+ * all of them would be a far larger change than this feature warrants. The
+ * router installs the loaded map once at construction via
+ * `setAgentProviderOverrides`.
+ *
+ * Empty by default, so behavior is unchanged for anyone who never writes the
+ * key — the category defaults below remain authoritative.
+ */
+let agentProviderOverrides = {};
+/**
+ * Per-provider default model, from the router config's `providers` map.
+ *
+ * Needed because the category defaults in `DEFAULT_CATEGORY_MODELS` pair a
+ * provider with a provider-specific model id. If a user writes
+ * `{ "provider": "ollama" }` and we inherited the category *model* too, the
+ * agent would be routed to ollama asking for `claude-sonnet-4-6` — a model that
+ * provider cannot serve. Changing provider without naming a model must fall
+ * back to that provider's own default, not the previous provider's model.
+ */
+let providerDefaultModels = {};
+/**
+ * Install the on-disk per-agent overrides (issue #568). Called by the router
+ * service after `loadRouterConfig()` has validated them.
+ *
+ * Replaces the whole map rather than merging, so reloading a config that
+ * removed an entry actually removes it.
+ *
+ * @param overrides validated `agentOverrides` map
+ * @param defaultModels per-provider default model ids, so a provider-only
+ *   override resolves to a model that provider can actually serve
+ */
+export function setAgentProviderOverrides(overrides, defaultModels) {
+    agentProviderOverrides = { ...(overrides ?? {}) };
+    providerDefaultModels = { ...(defaultModels ?? {}) };
+}
+/** Current on-disk per-agent overrides. Primarily for diagnostics and tests. */
+export function getAgentProviderOverrides() {
+    return agentProviderOverrides;
+}
+/** Clear installed overrides. For tests. */
+export function resetAgentProviderOverrides() {
+    agentProviderOverrides = {};
+    providerDefaultModels = {};
+}
 /**
- * Get the preferred model for an agent type
+ * Get the preferred model for an agent type.
+ *
+ * Resolution order (issue #568):
+ *   1. `agentOverrides[agentType]` from `.agentic-qe/llm-config.json` — the
+ *      user's explicit, hand-written intent, so it wins.
+ *   2. the agent's category default (`AGENT_CATEGORY_MAP` ->
+ *      `DEFAULT_CATEGORY_MODELS`).
+ *
+ * An override is a *partial*: fields it does not set keep their category
+ * default, so `{ "provider": "ollama" }` re-provisions the provider without
+ * forcing the user to also restate temperature, token budget, and priority.
+ *
  * @param agentType - The agent type identifier
  * @returns The model preference configuration
  */
 export function getPreferredModelForAgent(agentType) {
     const category = getAgentRoutingCategory(agentType);
-    return DEFAULT_CATEGORY_MODELS[category];
+    const base = DEFAULT_CATEGORY_MODELS[category];
+    const override = agentProviderOverrides[agentType];
+    if (!override)
+        return base;
+    // Changing provider without naming a model must NOT inherit the previous
+    // provider's model id (see `providerDefaultModels`). Prefer that provider's
+    // own default; only keep the category model when the provider is unchanged.
+    const switchingProvider = override.provider !== undefined && override.provider !== base.provider;
+    const resolvedModel = override.model ??
+        (switchingProvider ? providerDefaultModels[override.provider] : undefined);
+    return {
+        ...base,
+        ...(override.provider !== undefined ? { provider: override.provider } : {}),
+        ...(resolvedModel !== undefined ? { model: resolvedModel } : {}),
+        ...(override.temperature !== undefined ? { temperature: override.temperature } : {}),
+        ...(override.maxTokens !== undefined ? { maxTokens: override.maxTokens } : {}),
+        // An explicit on-disk entry outranks the built-in category rule by default,
+        // so it isn't quietly out-prioritized by DEFAULT_ROUTING_OVERRIDES.
+        priority: override.priority ?? base.priority + 100,
+    };
 }
 /**
  * Get capability requirements for an agent type
@@ -410,6 +493,45 @@ export function createAgentRoutingRule(agentType) {
         priority: preference.priority,
     };
 }
+/**
+ * Build routing rules for exactly the agent types the user overrode on disk
+ * (issue #568).
+ *
+ * Why a separate builder rather than `createAgentRoutingRule`: that one also
+ * constrains on `requiresReasoning`, which is right for the generated
+ * whole-roster ruleset but wrong here — a user who wrote
+ * `"qe-mutation-tester": { "provider": "ollama" }` means *always*, not "only when
+ * the request happens to be flagged as needing reasoning". These rules match on
+ * agent type alone.
+ *
+ * Returns `[]` when nothing is overridden, so a project without the key gets the
+ * exact rule set it got before.
+ *
+ * @returns Routing rules, highest priority first
+ */
+export function createOverrideRoutingRules() {
+    return Object.keys(agentProviderOverrides)
+        .map((agentType) => {
+        const preference = getPreferredModelForAgent(agentType);
+        return {
+            id: `agent-override-${agentType}`,
+            name: `User override: ${agentType} -> ${preference.provider}/${preference.model}`,
+            description: `Per-agent routing override from .agentic-qe/llm-config.json ` +
+                `(agentOverrides["${agentType}"])`,
+            condition: { agentType: [agentType] },
+            action: {
+                provider: preference.provider,
+                model: preference.model,
+                temperature: preference.temperature,
+                maxTokens: preference.maxTokens,
+                priority: preference.priority,
+            },
+            enabled: true,
+            priority: preference.priority,
+        };
+    })
+        .sort((a, b) => b.priority - a.priority);
+}
 /**
  * Create routing rules for all agents in a category
  * @param category - The agent category

package/dist/shared/llm/router/config-store.d.ts

@@ -17,7 +17,7 @@
  * state — we don't disable it implicitly, because users may set keys
  * later via `aqe llm config --set`.
  */
-import type { RouterConfig, ExtendedProviderType } from './types.js';
+import type { RouterConfig, ExtendedProviderType, AgentProviderOverride } from './types.js';
 /** Filename under .agentic-qe/ */
 export declare const ROUTER_CONFIG_FILENAME = "llm-config.json";
 /**
@@ -52,6 +52,22 @@ export declare function saveRouterConfigFile(config: Partial<RouterConfig>, proj
  * top-level scalars use last-wins.
  */
 export declare function mergeRouterConfig(base: RouterConfig, override: Partial<RouterConfig>): RouterConfig;
+/**
+ * Validate and normalize an on-disk `agentOverrides` map (issue #568).
+ *
+ * User-hand-edited config is untrusted input: drop entries that name a provider
+ * we cannot construct, and strip any `apiKey`-shaped field that leaked in — the
+ * same "never persist API keys" discipline `saveRouterConfigFile` already
+ * enforces for `providers.*`.
+ *
+ * Returns the cleaned map plus human-readable warnings for the caller to log.
+ * Invalid entries are dropped, never thrown on: a typo in one agent key must not
+ * take down router initialization for the whole project.
+ */
+export declare function sanitizeAgentOverrides(raw: unknown): {
+    overrides: Record<string, AgentProviderOverride>;
+    warnings: string[];
+};
 /**
  * Apply env-detection on top of a merged config: providers whose API
  * keys are present in env are force-enabled (so a user who sets