agentic-qe 3.12.3 → 3.13.1

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

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

@@ -21,6 +21,11 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { findProjectRoot } from '../../../kernel/unified-memory.js';
 import { DEFAULT_ROUTER_CONFIG, ALL_PROVIDER_TYPES } from './types.js';
+import { createLogger } from '../../../logging/logger-factory.js';
+// `console.warn` is not usable here: in MCP stdio mode stdout is the protocol
+// channel and console output is suppressed, so a config warning written that
+// way is invisible in the most common way AQE runs (issue #568).
+const logger = createLogger('llm/router/config-store');
 /** Filename under .agentic-qe/ */
 export const ROUTER_CONFIG_FILENAME = 'llm-config.json';
 /**
@@ -39,6 +44,10 @@ const PROVIDER_ENV_KEYS = {
     // availability is gated on the `claude` binary being on PATH (see the
     // provider's isAvailable()).
     'claude-code': [],
+    // ADR-124 M3.5: codex authenticates via the user's ChatGPT login
+    // (subscription), NOT an env key. Availability is gated on the `codex`
+    // binary being on PATH (see the provider's isAvailable()).
+    codex: [],
     openai: ['OPENAI_API_KEY'],
     ollama: [], // ollama is local; no key required
     openrouter: ['OPENROUTER_API_KEY'],
@@ -59,6 +68,7 @@ const PROVIDER_ENV_KEYS = {
 const RUNTIME_CONSTRUCTIBLE_PROVIDERS = new Set([
     'claude',
     'claude-code',
+    'codex',
     'openai',
     'ollama',
     'openrouter',
@@ -197,8 +207,97 @@ export function mergeRouterConfig(base, override) {
             };
         }
     }
+    // Issue #568: `agentOverrides` gets keyed-object merge semantics (like
+    // `providers`), NOT the shallow-replace treatment `fallbackChain` gets.
+    // Overriding one agent type must not wipe the rest.
+    if (base.agentOverrides || override.agentOverrides) {
+        merged.agentOverrides = { ...(base.agentOverrides ?? {}) };
+        for (const [agentType, cfg] of Object.entries(override.agentOverrides ?? {})) {
+            if (!cfg)
+                continue;
+            merged.agentOverrides[agentType] = {
+                ...(base.agentOverrides?.[agentType] ?? {}),
+                ...cfg,
+            };
+        }
+    }
     return merged;
 }
+/**
+ * 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 function sanitizeAgentOverrides(raw) {
+    const overrides = {};
+    const warnings = [];
+    if (raw === undefined || raw === null)
+        return { overrides, warnings };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        warnings.push('`agentOverrides` must be an object keyed by agent type; ignoring it.');
+        return { overrides, warnings };
+    }
+    for (const [agentType, value] of Object.entries(raw)) {
+        if (!agentType.trim())
+            continue;
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            warnings.push(`agentOverrides["${agentType}"] must be an object; ignoring it.`);
+            continue;
+        }
+        const entry = value;
+        const cleaned = {};
+        if (entry.provider !== undefined) {
+            const provider = entry.provider;
+            if (!ALL_PROVIDER_TYPES.includes(provider)) {
+                warnings.push(`agentOverrides["${agentType}"].provider "${String(entry.provider)}" is not a known ` +
+                    `provider (${ALL_PROVIDER_TYPES.join(', ')}); ignoring this entry.`);
+                continue;
+            }
+            if (!RUNTIME_CONSTRUCTIBLE_PROVIDERS.has(provider)) {
+                warnings.push(`agentOverrides["${agentType}"].provider "${provider}" cannot be instantiated at ` +
+                    `runtime yet; ignoring this entry.`);
+                continue;
+            }
+            cleaned.provider = provider;
+        }
+        if (typeof entry.model === 'string' && entry.model.trim()) {
+            cleaned.model = entry.model.trim();
+        }
+        if (typeof entry.temperature === 'number' && Number.isFinite(entry.temperature)) {
+            cleaned.temperature = entry.temperature;
+        }
+        if (typeof entry.maxTokens === 'number' && Number.isFinite(entry.maxTokens)) {
+            cleaned.maxTokens = entry.maxTokens;
+        }
+        if (typeof entry.priority === 'number' && Number.isFinite(entry.priority)) {
+            cleaned.priority = entry.priority;
+        }
+        // Secrets are already dropped by construction: `cleaned` is an ALLOW-LIST,
+        // so anything not explicitly copied above never survives. This check exists
+        // only so a user who pasted a credential in here is TOLD it was discarded
+        // rather than silently wondering why their key isn't being used.
+        // Deliberately does not echo the value.
+        const secretish = Object.keys(entry).filter(k => /^(api[-_]?key|key|token|secret|password|passwd|auth|authorization|bearer|credential)s?$/i.test(k));
+        if (secretish.length > 0) {
+            warnings.push(`agentOverrides["${agentType}"] contained credential-shaped field(s) ` +
+                `[${secretish.join(', ')}] — discarded, not persisted, not logged. Credentials belong ` +
+                `in environment variables, never in .agentic-qe/llm-config.json.`);
+        }
+        if (Object.keys(cleaned).length === 0) {
+            warnings.push(`agentOverrides["${agentType}"] had no usable fields; ignoring it.`);
+            continue;
+        }
+        overrides[agentType] = cleaned;
+    }
+    return { overrides, warnings };
+}
 /**
  * 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
@@ -282,6 +381,15 @@ export function resolveProviderOverrideFromEnv(env = process.env) {
 export function loadRouterConfig(options = {}) {
     const env = options.env ?? process.env;
     const onDisk = loadRouterConfigFile(options.projectRoot);
+    // Issue #568: validate the hand-editable per-agent map before it reaches the
+    // router. Bad entries are dropped with a warning, never fatal.
+    if (onDisk.agentOverrides !== undefined) {
+        const { overrides, warnings } = sanitizeAgentOverrides(onDisk.agentOverrides);
+        for (const warning of warnings) {
+            logger.warn(`[llm-config] ${warning}`);
+        }
+        onDisk.agentOverrides = overrides;
+    }
     const merged = mergeRouterConfig(DEFAULT_ROUTER_CONFIG, onDisk);
     // ADR-123: an explicit `enabled: false` on disk is never resurrected by env.
     const explicitlyDisabled = collectExplicitlyDisabled(onDisk);

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

@@ -518,8 +518,8 @@ export class HybridRouter {
                     metadata: params.metadata,
                 });
                 // ADR-123: persist the charge to the cross-process ledger so budgets
-                // hold across a fleet of processes.
-                this.providerManager.recordResponseSpend(response);
+                // hold across a fleet of processes. ADR-124 M2.3: attribute to the agent.
+                this.providerManager.recordResponseSpend(response, params.agentType);
                 const callLatency = Date.now() - callStartTime;
                 // Record success in legacy tracker
                 this.metrics.recordSuccess(providerType);

package/dist/shared/llm/router/index.d.ts

@@ -21,11 +21,11 @@
  * - Routing decision audit log
  * - Cost breakdown by agent type
  */
-export type { ExtendedProviderType, ProviderCapabilities, ExtendedLLMProvider, RequiredFeature, ModelFamily, ModelTier, ModelMapping, ModelRegistry, MessageFormat, SystemPromptStrategy, ToolSchemaFormat, TranslatedMessages, ToolDefinition, TranslatedTools, TranslationOptions, PromptTranslator, RoutingMode, TaskComplexity, RuleCondition, RuleAction, RoutingRule, SelectionReason, RoutingDecision, FallbackBehavior, FallbackChainEntry, FallbackChain, RouterConfig, ChatParams, ChatResponse, StreamChunk, ProviderRoutingMetrics, RouterMetrics, } from './types';
+export type { ExtendedProviderType, ProviderCapabilities, ExtendedLLMProvider, RequiredFeature, ModelFamily, ModelTier, ModelMapping, ModelRegistry, MessageFormat, SystemPromptStrategy, ToolSchemaFormat, TranslatedMessages, ToolDefinition, TranslatedTools, TranslationOptions, PromptTranslator, RoutingMode, TaskComplexity, RuleCondition, RuleAction, RoutingRule, SelectionReason, RoutingDecision, FallbackBehavior, FallbackChainEntry, FallbackChain, RouterConfig, AgentProviderOverride, ChatParams, ChatResponse, StreamChunk, ProviderRoutingMetrics, RouterMetrics, } from './types';
 export { ALL_PROVIDER_TYPES, DEFAULT_PROVIDER_CAPABILITIES, DEFAULT_FALLBACK_BEHAVIOR, DEFAULT_ROUTER_CONFIG, } from './types';
 export { RoutingRuleEngine, DEFAULT_QE_ROUTING_RULES, createRoutingRule, mergeWithDefaultRules, inferComplexity, getExtendedAgentCategory, getModelPreferenceForAgent, agentRequiresAdvancedReasoning, agentIsCostSensitive, agentIsLatencySensitive, getAgentTypesInCategory, getAllAgentCategories, getCategoryModelPreference, createAgentBasedRoutingRule, createCategoryBasedRoutingRules, generateComprehensiveAgentRules, mergeAgentAwareRules, } from './routing-rules';
 export type { ExtendedAgentCategory } from './routing-rules';
 export type { AgentCategory, ModelPreference, AgentCapabilityRequirements, AgentRoutingConfig, AgentRouterConfig, AgentRoutingOverride, } from './agent-router-config';
-export { DEFAULT_CATEGORY_MODELS, AGENT_CATEGORY_MAP, DEFAULT_CATEGORY_CAPABILITIES, DEFAULT_ROUTING_OVERRIDES, ALTERNATIVE_MODELS, getAgentRoutingCategory, getPreferredModelForAgent, getAgentCapabilityRequirements, getAgentsByCategory, requiresAdvancedReasoning, isCostSensitive, isLatencySensitive, createAgentRoutingRule, createCategoryRoutingRules, createAgentAwareRules, createAllAgentRoutingRules, getAlternativeModelsForAgent, buildAgentRouterConfig, } from './agent-router-config';
+export { DEFAULT_CATEGORY_MODELS, AGENT_CATEGORY_MAP, DEFAULT_CATEGORY_CAPABILITIES, DEFAULT_ROUTING_OVERRIDES, ALTERNATIVE_MODELS, getAgentRoutingCategory, getPreferredModelForAgent, getAgentCapabilityRequirements, getAgentsByCategory, requiresAdvancedReasoning, isCostSensitive, isLatencySensitive, createAgentRoutingRule, createCategoryRoutingRules, createAgentAwareRules, createAllAgentRoutingRules, setAgentProviderOverrides, getAgentProviderOverrides, resetAgentProviderOverrides, createOverrideRoutingRules, getAlternativeModelsForAgent, buildAgentRouterConfig, } from './agent-router-config';
 export { HybridRouter, createHybridRouter, createQERouter, } from './hybrid-router';
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/llm/router/index.js

@@ -38,6 +38,8 @@ DEFAULT_CATEGORY_MODELS, AGENT_CATEGORY_MAP, DEFAULT_CATEGORY_CAPABILITIES, DEFA
 getAgentRoutingCategory, getPreferredModelForAgent, getAgentCapabilityRequirements, getAgentsByCategory, requiresAdvancedReasoning, isCostSensitive, isLatencySensitive, 
 // Rule generation
 createAgentRoutingRule, createCategoryRoutingRules, createAgentAwareRules, createAllAgentRoutingRules, 
+// On-disk per-agent overrides (issue #568)
+setAgentProviderOverrides, getAgentProviderOverrides, resetAgentProviderOverrides, createOverrideRoutingRules, 
 // Alternative models
 getAlternativeModelsForAgent, 
 // Configuration builder

package/dist/shared/llm/router/types.d.ts

@@ -562,6 +562,50 @@ export interface RouterConfig {
     cacheConfig?: RouterCacheConfig;
     /** Audit logging configuration (ADR-043) */
     auditConfig?: AuditConfig;
+    /**
+     * Per-agent-type provider/model overrides (issue #568).
+     *
+     * Keyed by agent type (`qe-security-scanner`, `qe-test-architect`, ...).
+     * These take priority over the category defaults in
+     * `agent-router-config.ts` (`AGENT_CATEGORY_MAP` -> `DEFAULT_CATEGORY_MODELS`),
+     * letting a user route security-sensitive agents to a stronger model and
+     * mechanical ones to a cheap/local provider without touching
+     * `defaultProvider`.
+     *
+     * Set on disk in `.agentic-qe/llm-config.json`:
+     * ```jsonc
+     * {
+     *   "defaultProvider": "claude-code",
+     *   "agentOverrides": {
+     *     "qe-security-scanner": { "provider": "cognitum", "model": "cognitum-high" },
+     *     "qe-mutation-tester":  { "provider": "ollama" }
+     *   }
+     * }
+     * ```
+     * Unset fields keep their category default. Never put API keys here.
+     */
+    agentOverrides?: Record<string, AgentProviderOverride>;
+}
+/**
+ * On-disk, per-agent-type routing override (issue #568).
+ *
+ * A deliberately narrow, hand-editable subset of `ModelPreference` from
+ * `agent-router-config.ts`: `provider` and `model` are the only fields a user
+ * realistically wants to set by hand, but `temperature`/`maxTokens`/`priority`
+ * are accepted for parity with the in-process `AgentRoutingOverride` mechanism.
+ * Every field is optional and falls back to the agent's category default.
+ */
+export interface AgentProviderOverride {
+    /** Provider to route this agent type through. */
+    provider?: ExtendedProviderType;
+    /** Model identifier within that provider. */
+    model?: string;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Max tokens for typical requests. */
+    maxTokens?: number;
+    /** Rule priority; higher wins. Defaults to above the category rule. */
+    priority?: number;
 }
 /**
  * Routing context provided with chat requests

package/dist/shared/llm/router/types.js

@@ -24,6 +24,7 @@
 export const ALL_PROVIDER_TYPES = [
     'claude',
     'claude-code', // ADR-123: subscription-billed via `claude -p`
+    'codex', // ADR-124 M3.5: subscription-billed via `codex exec` (issue #568)
     'openai',
     'ollama',
     'openrouter',

package/dist/shared/llm/spend-ledger.d.ts

@@ -28,6 +28,12 @@ export interface SpendEntry {
     promptTokens: number;
     completionTokens: number;
     requestId: string;
+    /**
+     * ADR-124 M2.3: the QE agent type/name this charge is attributed to (e.g.
+     * 'qe-security-scanner'). Optional — null when the call site has no agent
+     * context. Enables per-agent cost attribution across the fleet.
+     */
+    agent?: string;
 }
 /** Cross-process spend ledger. */
 export interface SpendLedger {
@@ -35,16 +41,33 @@ export interface SpendLedger {
     record(entry: SpendEntry): void;
     /** Total USD charged within the last `windowMs` (rolling window ending now). */
     spentSince(windowMs: number, nowMs?: number): number;
+    /**
+     * ADR-124 M2.3: USD charged within the last `windowMs`, broken down by agent
+     * type. Charges with no agent are grouped under '(unattributed)'.
+     */
+    spentByAgentSince(windowMs: number, nowMs?: number): Record<string, number>;
 }
+/** Bucket used for charges recorded without an agent context. */
+export declare const UNATTRIBUTED_AGENT = "(unattributed)";
 /**
  * SQLite-backed ledger. Cross-process because every process opens its own
  * connection to the same WAL-mode `memory.db`.
  */
 export declare class SqliteSpendLedger implements SpendLedger {
     private readonly db;
+    /**
+     * Whether the `agent_type` column exists. If the additive migration couldn't
+     * run (e.g. transient lock), this stays false and record() INSERTs WITHOUT the
+     * column — so spend is still recorded and the ADR-123 budget cap still holds.
+     * A qe-court review (ADR-124) caught the original bug: a swallowed migration
+     * made every INSERT reference a missing column, throw, get caught, and silently
+     * drop ALL spend — bypassing the budget cap (the #557 class).
+     */
+    private hasAgentColumn;
     constructor(db: DatabaseType);
     record(entry: SpendEntry): void;
     spentSince(windowMs: number, nowMs?: number): number;
+    spentByAgentSince(windowMs: number, nowMs?: number): Record<string, number>;
 }
 /**
  * In-process fallback ledger. Used when no unified DB is available. Enforces
@@ -54,6 +77,7 @@ export declare class InMemorySpendLedger implements SpendLedger {
     private readonly entries;
     record(entry: SpendEntry): void;
     spentSince(windowMs: number, nowMs?: number): number;
+    spentByAgentSince(windowMs: number, nowMs?: number): Record<string, number>;
 }
 /**
  * Build the default ledger. Prefers the unified `memory.db` (cross-process);

package/dist/shared/llm/spend-ledger.js

@@ -17,6 +17,8 @@
  * connections (one per process) to a WAL-mode DB is exactly the supported
  * cross-process pattern.
  */
+/** Bucket used for charges recorded without an agent context. */
+export const UNATTRIBUTED_AGENT = '(unattributed)';
 const CREATE_TABLE_SQL = `
 CREATE TABLE IF NOT EXISTS llm_spend (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -37,27 +39,72 @@ CREATE INDEX IF NOT EXISTS idx_llm_spend_ts ON llm_spend(ts);
  */
 export class SqliteSpendLedger {
     db;
+    /**
+     * Whether the `agent_type` column exists. If the additive migration couldn't
+     * run (e.g. transient lock), this stays false and record() INSERTs WITHOUT the
+     * column — so spend is still recorded and the ADR-123 budget cap still holds.
+     * A qe-court review (ADR-124) caught the original bug: a swallowed migration
+     * made every INSERT reference a missing column, throw, get caught, and silently
+     * drop ALL spend — bypassing the budget cap (the #557 class).
+     */
+    hasAgentColumn = false;
     constructor(db) {
         this.db = db;
         // Additive schema only — CREATE TABLE/INDEX IF NOT EXISTS never drops data.
         this.db.exec(CREATE_TABLE_SQL);
+        // ADR-124 M2.3: additive `agent_type` column for per-agent attribution.
+        // ALTER TABLE ADD COLUMN is non-destructive (existing rows get NULL); guarded
+        // so re-opening an already-migrated DB is a no-op. Never drops or rewrites.
+        try {
+            const cols = this.db.prepare(`PRAGMA table_info(llm_spend)`).all();
+            if (!cols.some((c) => c.name === 'agent_type')) {
+                this.db.exec(`ALTER TABLE llm_spend ADD COLUMN agent_type TEXT`);
+            }
+            this.db.exec(`CREATE INDEX IF NOT EXISTS idx_llm_spend_agent ON llm_spend(agent_type)`);
+            this.hasAgentColumn = true;
+        }
+        catch {
+            // Attribution is best-effort; never block ledger use on the migration.
+            // hasAgentColumn stays false → record() degrades to un-attributed INSERTs.
+        }
     }
     record(entry) {
         try {
-            this.db
-                .prepare(`INSERT INTO llm_spend
-             (ts, provider, model, cost_usd, cost_source, prompt_tokens, completion_tokens, request_id)
-           VALUES (@ts, @provider, @model, @cost_usd, @cost_source, @prompt_tokens, @completion_tokens, @request_id)`)
-                .run({
-                ts: Date.now(),
-                provider: entry.provider,
-                model: entry.model,
-                cost_usd: entry.costUsd,
-                cost_source: entry.costSource,
-                prompt_tokens: entry.promptTokens,
-                completion_tokens: entry.completionTokens,
-                request_id: entry.requestId,
-            });
+            if (this.hasAgentColumn) {
+                this.db
+                    .prepare(`INSERT INTO llm_spend
+               (ts, provider, model, cost_usd, cost_source, prompt_tokens, completion_tokens, request_id, agent_type)
+             VALUES (@ts, @provider, @model, @cost_usd, @cost_source, @prompt_tokens, @completion_tokens, @request_id, @agent_type)`)
+                    .run({
+                    ts: Date.now(),
+                    provider: entry.provider,
+                    model: entry.model,
+                    cost_usd: entry.costUsd,
+                    cost_source: entry.costSource,
+                    prompt_tokens: entry.promptTokens,
+                    completion_tokens: entry.completionTokens,
+                    request_id: entry.requestId,
+                    agent_type: entry.agent ?? null,
+                });
+            }
+            else {
+                // Column absent (migration couldn't run) — still record spend so the
+                // budget cap holds; just without per-agent attribution.
+                this.db
+                    .prepare(`INSERT INTO llm_spend
+               (ts, provider, model, cost_usd, cost_source, prompt_tokens, completion_tokens, request_id)
+             VALUES (@ts, @provider, @model, @cost_usd, @cost_source, @prompt_tokens, @completion_tokens, @request_id)`)
+                    .run({
+                    ts: Date.now(),
+                    provider: entry.provider,
+                    model: entry.model,
+                    cost_usd: entry.costUsd,
+                    cost_source: entry.costSource,
+                    prompt_tokens: entry.promptTokens,
+                    completion_tokens: entry.completionTokens,
+                    request_id: entry.requestId,
+                });
+            }
         }
         catch {
             // A ledger write must never break a generation call.
@@ -74,6 +121,21 @@ export class SqliteSpendLedger {
             return 0;
         }
     }
+    spentByAgentSince(windowMs, nowMs = Date.now()) {
+        try {
+            const rows = this.db
+                .prepare(`SELECT COALESCE(agent_type, ?) AS agent, COALESCE(SUM(cost_usd), 0) AS total
+             FROM llm_spend WHERE ts >= ? GROUP BY COALESCE(agent_type, ?)`)
+                .all(UNATTRIBUTED_AGENT, nowMs - windowMs, UNATTRIBUTED_AGENT);
+            const out = {};
+            for (const r of rows)
+                out[r.agent] = r.total;
+            return out;
+        }
+        catch {
+            return {};
+        }
+    }
 }
 /**
  * In-process fallback ledger. Used when no unified DB is available. Enforces
@@ -82,7 +144,7 @@ export class SqliteSpendLedger {
 export class InMemorySpendLedger {
     entries = [];
     record(entry) {
-        this.entries.push({ ts: Date.now(), costUsd: entry.costUsd });
+        this.entries.push({ ts: Date.now(), costUsd: entry.costUsd, agent: entry.agent ?? UNATTRIBUTED_AGENT });
     }
     spentSince(windowMs, nowMs = Date.now()) {
         const cutoff = nowMs - windowMs;
@@ -93,6 +155,15 @@ export class InMemorySpendLedger {
         }
         return total;
     }
+    spentByAgentSince(windowMs, nowMs = Date.now()) {
+        const cutoff = nowMs - windowMs;
+        const out = {};
+        for (const e of this.entries) {
+            if (e.ts >= cutoff)
+                out[e.agent] = (out[e.agent] ?? 0) + e.costUsd;
+        }
+        return out;
+    }
 }
 /**
  * Build the default ledger. Prefers the unified `memory.db` (cross-process);

package/dist/shared/llm/translation/message-formatter.js

@@ -16,6 +16,7 @@
 const SYSTEM_PROMPT_STRATEGIES = {
     claude: 'native', // Anthropic supports separate system param
     'claude-code': 'native', // ADR-123: passed via --append-system-prompt
+    codex: 'native', // ADR-124 M3.5: provider flattens system into the prompt
     openai: 'native', // OpenAI supports system role messages
     ollama: 'native', // Ollama supports system role
     openrouter: 'native', // OpenRouter passes through to underlying provider

package/dist/shared/safe-db.d.ts

@@ -18,6 +18,16 @@ export interface SafeDbOptions {
     busyTimeout?: number;
     /** Enable WAL mode (default: true for writable, false for readonly) */
     walMode?: boolean;
+    /**
+     * M3.2: on a malformed/corrupt existing DB, auto-restore the newest verified
+     * backup (from `.agentic-qe/backups/verified/`) and park the corrupt original,
+     * instead of opening a broken DB. Default false; enable for the unified
+     * `memory.db` open. Non-destructive: the corrupt file is renamed, never deleted,
+     * and nothing happens if no verified backup exists. Ignored for readonly opens.
+     */
+    autoRestore?: boolean;
+    /** Override the verified-backup directory used by autoRestore. */
+    backupDir?: string;
 }
 /**
  * Open a SQLite database with safe defaults that prevent corruption.