agentic-qe 3.9.30 → 3.9.31

package/dist/cli/commands/learning.js

@@ -65,6 +65,7 @@ Examples:
     registerDreamCommand(learning);
     registerRepairCommand(learning);
     registerHealthCommand(learning);
+    registerLoopHealthCommand(learning);
     return learning;
 }
 // ============================================================================
@@ -1414,6 +1415,199 @@ function registerHealthCommand(learning) {
     });
 }
 // ============================================================================
+// Subcommand: loop-health (#488 B.2)
+// ============================================================================
+/**
+ * Component staleness thresholds (ms). Each component has its own expected
+ * cadence — the bridge polls every 5s, the learning worker ticks every 30
+ * min, the dream scheduler is variable. Anything older than ~2x its cadence
+ * counts as stale and operators should investigate.
+ */
+const COMPONENT_STALE_THRESHOLDS = {
+    bridge: 30_000, // 5s poll → stale at 30s
+    learningWorker: 2 * 3600_000, // 30 min tick → stale at 2h
+    dreamScheduler: 2 * 3600_000, // similar cadence to worker
+};
+function registerLoopHealthCommand(learning) {
+    learning
+        .command('loop-health')
+        .description('Show pipeline component liveness for the self-learning loop')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const projectRoot = findProjectRoot();
+            const dbPath = path.join(projectRoot, '.agentic-qe', 'memory.db');
+            if (!existsSync(dbPath)) {
+                throw new Error('Database not found. Run "aqe init --auto" first.');
+            }
+            const db = openDatabase(dbPath, { readonly: true });
+            let raw;
+            try {
+                // Try the unified kv_store first (kernel-owned key).
+                const row = db
+                    .prepare(`SELECT value FROM kv_store WHERE key = 'learning:loop-health' LIMIT 1`)
+                    .get();
+                raw = row?.value;
+            }
+            catch {
+                // kv_store may not exist yet on a freshly-init'd shop.
+            }
+            // ADR-095: routing diversification stats (7-day rolling window)
+            let routingStats = null;
+            try {
+                const colCheck = db
+                    .prepare("PRAGMA table_info(routing_outcomes)")
+                    .all();
+                const hasExploration = colCheck.some((c) => c.name === 'exploration');
+                if (hasExploration) {
+                    const totals = db
+                        .prepare(`SELECT
+                   COUNT(*) AS total,
+                   SUM(CASE WHEN exploration = 1 THEN 1 ELSE 0 END) AS explore,
+                   AVG(criticality) AS avgCrit,
+                   AVG(q_weight) AS avgQ
+                 FROM routing_outcomes
+                 WHERE created_at >= datetime('now', '-7 days')`)
+                        .get();
+                    const total = totals.total ?? 0;
+                    const explore = totals.explore ?? 0;
+                    const exploit = total - explore;
+                    const exploitQ = db
+                        .prepare(`SELECT AVG(quality_score) AS avgQ FROM routing_outcomes
+                  WHERE exploration = 0 AND quality_score >= 0
+                    AND created_at >= datetime('now', '-7 days')`)
+                        .get();
+                    const exploreQ = db
+                        .prepare(`SELECT AVG(quality_score) AS avgQ FROM routing_outcomes
+                  WHERE exploration = 1 AND quality_score >= 0
+                    AND created_at >= datetime('now', '-7 days')`)
+                        .get();
+                    routingStats = {
+                        totalDecisions: total,
+                        explorationCount: explore,
+                        exploitCount: exploit,
+                        explorationRate: total > 0 ? explore / total : 0,
+                        avgQualityExploit: exploitQ.avgQ,
+                        avgQualityExplore: exploreQ.avgQ,
+                        avgCriticality: totals.avgCrit,
+                        avgQWeight: totals.avgQ,
+                    };
+                }
+            }
+            catch {
+                // routing_outcomes missing or pre-ADR-095 schema — skip silently.
+            }
+            db.close();
+            let health = null;
+            if (raw) {
+                try {
+                    health = safeJsonParse(raw);
+                }
+                catch {
+                    health = null;
+                }
+            }
+            const now = Date.now();
+            const verdict = (componentKey, c) => {
+                const threshold = COMPONENT_STALE_THRESHOLDS[componentKey] ?? 600_000;
+                if (!c || !c.lastSuccessAt)
+                    return 'never-ran';
+                const age = now - new Date(c.lastSuccessAt).getTime();
+                return age > threshold ? 'stale' : 'live';
+            };
+            if (options.json) {
+                if (!health) {
+                    printJson({
+                        overallLastSuccess: null,
+                        bootedAt: null,
+                        components: {},
+                        verdicts: {},
+                        routingDiversification: routingStats,
+                        note: 'No loop-health record yet. Workers must run at least once for this to populate.',
+                    });
+                    return;
+                }
+                const verdicts = {};
+                for (const key of Object.keys(health.components)) {
+                    verdicts[key] = verdict(key, health.components[key]);
+                }
+                printJson({ ...health, verdicts, routingDiversification: routingStats });
+                return;
+            }
+            console.log('');
+            console.log(chalk.bold('Self-Learning Loop Health'));
+            console.log('');
+            if (!health) {
+                console.log(chalk.dim('  No loop-health record yet.'));
+                console.log(chalk.dim('  Workers must run at least once to populate.'));
+                console.log(chalk.dim('  Start the daemon: aqe daemon start'));
+                // FALL THROUGH (no early return): routing-diversification stats may
+                // still be available even when loop-health components haven't ticked
+                // yet (e.g., routing happened via hook handlers but daemon-side
+                // workers never ran). Operators need both signals visible.
+            }
+            else {
+                console.log(`  Booted at:           ${chalk.dim(health.bootedAt)}`);
+                console.log(`  Last success (any):  ${health.overallLastSuccess || chalk.dim('(none yet)')}`);
+                console.log('');
+                console.log(chalk.bold('  Components:'));
+                const known = [
+                    ['bridge', 'CapturedExperienceBridge'],
+                    ['learningWorker', 'LearningConsolidationWorker'],
+                    ['dreamScheduler', 'DreamScheduler'],
+                ];
+                for (const [key, label] of known) {
+                    const c = health.components[key];
+                    const v = verdict(key, c);
+                    const colored = v === 'live'
+                        ? chalk.green('● live')
+                        : v === 'stale'
+                            ? chalk.yellow('● stale')
+                            : chalk.dim('○ never-ran');
+                    const lastSuccess = c?.lastSuccessAt || chalk.dim('(never)');
+                    const ticks = c
+                        ? `${c.successesSinceBoot}/${c.ticksSinceBoot} ticks ok`
+                        : chalk.dim('no ticks');
+                    console.log(`    ${label.padEnd(32)} ${colored.padEnd(20)} ${ticks}`);
+                    console.log(`      ${chalk.dim('last success:')} ${lastSuccess}`);
+                    if (c?.lastError) {
+                        console.log(`      ${chalk.red('last error:')} ${c.lastError.message} ${chalk.dim('(at ' + c.lastError.at + ')')}`);
+                    }
+                }
+                const stale = known.filter(([k, _]) => verdict(k, health.components[k]) === 'stale');
+                if (stale.length > 0) {
+                    console.log('');
+                    console.log(chalk.yellow(`  Warning: ${stale.length} component(s) stale — daemon may not be running or the loop is wedged.`));
+                }
+            }
+            // ADR-095: routing diversification dashboard
+            if (routingStats && routingStats.totalDecisions > 0) {
+                console.log('');
+                console.log(chalk.bold('  Routing diversification (last 7 days):'));
+                const ratePct = (routingStats.explorationRate * 100).toFixed(1);
+                console.log(`    Decisions:           ${routingStats.totalDecisions} (${routingStats.exploitCount} exploit, ${routingStats.explorationCount} explore = ${ratePct}%)`);
+                if (routingStats.avgQualityExploit !== null && routingStats.avgQualityExplore !== null) {
+                    const delta = routingStats.avgQualityExplore - routingStats.avgQualityExploit;
+                    const deltaStr = delta >= 0 ? chalk.green(`+${delta.toFixed(3)}`) : chalk.red(delta.toFixed(3));
+                    console.log(`    Avg quality:         exploit=${routingStats.avgQualityExploit.toFixed(3)}, explore=${routingStats.avgQualityExplore.toFixed(3)} (Δ ${deltaStr})`);
+                }
+                if (routingStats.avgCriticality !== null) {
+                    console.log(`    Avg mincut multiplier:  ${routingStats.avgCriticality.toFixed(2)} (1.0=full rate, 0.2=critical-topology dampening)`);
+                }
+                if (routingStats.avgQWeight !== null && routingStats.avgQWeight > 0) {
+                    console.log(`    Avg Q-weight:        ${routingStats.avgQWeight.toFixed(3)} (0=cold start, ${0.4} max)`);
+                }
+            }
+            console.log('');
+            return;
+        }
+        catch (error) {
+            printError(`loop-health failed: ${error instanceof Error ? error.message : 'unknown'}`);
+            throw error;
+        }
+    });
+}
+// ============================================================================
 // Exports
 // ============================================================================
 export { initializeLearningSystem } from './learning-helpers.js';

package/dist/init/phases/10-workers.js

@@ -121,12 +121,30 @@ if (existsSync(pidFile)) {
 const ts = new Date().toISOString();
 appendFileSync(logFile, '[' + ts + '] Starting AQE v3 Worker Daemon...\\n');
 
-// Find the best way to run aqe-mcp
+// Find the best way to run aqe-mcp.
+//
+// #488 B.1: candidate ordering matters for the pidfile contract. When we
+// spawn the real MCP binary directly, child.pid is the long-lived process
+// — \`process.kill(pid, 0)\` against the pidfile correctly reports liveness.
+// When we fall back to \`npx --yes agentic-qe mcp\`, child.pid is the npx
+// wrapper PID, which exits as soon as it has forked the real bundle. The
+// pidfile then points at a dead process and idempotency checks misbehave.
+//
+// We try in order: local .bin → local node_modules bundle → global install
+// via require.resolve → npx wrapper (last resort, with the caveat above).
 const candidates = [
   join(projectRoot, 'node_modules', '.bin', 'aqe-mcp'),
   join(projectRoot, 'node_modules', 'agentic-qe', 'dist', 'mcp', 'bundle.js'),
 ];
 
+// Probe globally-installed agentic-qe (npm install -g) via require.resolve.
+// This is the case the npx fallback used to silently cover with a bad PID.
+try {
+  candidates.push(require.resolve('agentic-qe/dist/mcp/bundle.js'));
+} catch {
+  // Not globally installed — fall through to npx fallback below.
+}
+
 let mcpCmd, mcpArgs;
 const binCandidate = candidates.find(c => existsSync(c));
 
@@ -139,6 +157,7 @@ if (binCandidate && binCandidate.endsWith('bundle.js')) {
 } else {
   mcpCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
   mcpArgs = ['--yes', 'agentic-qe', 'mcp'];
+  appendFileSync(logFile, '[' + ts + '] WARNING: using npx fallback — daemon.pid will point at the npx wrapper, not the MCP server. \`aqe daemon status\` may misreport liveness after the wrapper exits.\\n');
 }
 
 appendFileSync(logFile, '[' + ts + '] Using: ' + mcpCmd + ' ' + mcpArgs.join(' ') + '\\n');

package/dist/kernel/interfaces.d.ts

@@ -297,6 +297,18 @@ export interface KernelConfig {
      * can set false to skip the plugin-load cost.
      */
     enableExperienceBridge?: boolean;
+    /**
+     * Whether to start the DreamScheduler during initialize() (ADR-094).
+     * When true (default), dream cycles run inside the long-lived kernel
+     * process instead of hook subprocesses. Hook subprocesses keep only
+     * `incrementDreamExperience` — the kernel-side scheduler is the
+     * authoritative trigger.
+     *
+     * Long-lived processes (MCP server, daemon) want this true.
+     * Short-lived CLI commands that complete in <1s can set false to skip
+     * DreamEngine init cost.
+     */
+    enableDreamScheduler?: boolean;
 }
 /**
  * Event middleware interface for anti-drift and other event processing (ADR-060)

package/dist/kernel/kernel.d.ts

@@ -21,6 +21,7 @@ export declare class QEKernelImpl implements QEKernel {
     private _initialized;
     private _loopTracker;
     private _experienceBridge?;
+    private _dreamScheduler?;
     constructor(config?: Partial<KernelConfig>);
     get eventBus(): EventBus;
     get coordinator(): AgentCoordinator;

package/dist/kernel/kernel.js

@@ -19,6 +19,8 @@ import * as fs from 'fs';
 import { PluginLifecycleManager } from '../plugins/lifecycle';
 import { PluginCache } from '../plugins/cache';
 import { CapturedExperienceBridge } from '../bridge/captured-experience-bridge.js';
+import { DreamScheduler } from '../learning/dream/dream-scheduler.js';
+import { createDreamEngine } from '../learning/dream/dream-engine.js';
 // Import domain plugin factories
 import { createTestGenerationPlugin } from '../domains/test-generation/plugin';
 import { createTestExecutionPlugin } from '../domains/test-execution/plugin';
@@ -69,6 +71,10 @@ const DEFAULT_CONFIG = {
     // working out of the box. CLI commands that don't need event-driven
     // domain reactions opt out by passing `enableExperienceBridge: false`.
     enableExperienceBridge: true,
+    // ADR-094: kernel-side dream cycles. Defaults match the bridge — long-lived
+    // processes start the scheduler so dream cycles run in the kernel rather
+    // than inside hook subprocesses. Short-lived CLIs opt out.
+    enableDreamScheduler: true,
 };
 export class QEKernelImpl {
     _eventBus;
@@ -83,6 +89,10 @@ export class QEKernelImpl {
     // Issue #479: drains captured_experiences into the eventBus so hook-driven
     // activity reaches the 13 domain plugins' subscribeToEvents() handlers.
     _experienceBridge;
+    // ADR-094: kernel-side dream cycles. Replaces the in-hook
+    // checkAndTriggerDream path so 10-second SQLite write transactions move
+    // out of short-lived hook subprocesses into the long-lived kernel.
+    _dreamScheduler;
     constructor(config = {}) {
         this._config = { ...DEFAULT_CONFIG, ...config };
         this._startTime = new Date();
@@ -262,9 +272,56 @@ export class QEKernelImpl {
                 this._experienceBridge = undefined;
             }
         }
+        // ADR-094: Start the kernel-side DreamScheduler so dream cycles run in
+        // the long-lived process. Hook subprocesses no longer trigger dreams —
+        // they only bump the experience counter (incrementDreamExperience).
+        // The scheduler subscribes to its own event triggers (quality-gate
+        // failure, domain milestones) and runs time-based dreams on its own
+        // cadence (default 1h). DreamEngine.ensureConceptsLoaded() auto-loads
+        // patterns from qe_patterns, so no separate ReasoningBank is needed here.
+        if (this._config.enableDreamScheduler !== false) {
+            try {
+                const dreamEngine = createDreamEngine({
+                    maxDurationMs: 10_000,
+                    minConceptsRequired: 3,
+                });
+                await dreamEngine.initialize();
+                this._dreamScheduler = new DreamScheduler({
+                    dreamEngine,
+                    eventBus: this._eventBus,
+                    memoryBackend: this._memory,
+                });
+                await this._dreamScheduler.initialize();
+                this._dreamScheduler.start();
+            }
+            catch (err) {
+                console.warn('[QEKernel] DreamScheduler failed to start:', err instanceof Error ? err.message : err);
+                // Tear down anything we partially constructed so we don't leak a
+                // half-initialized scheduler (e.g., engine init succeeded but
+                // scheduler.start threw).
+                if (this._dreamScheduler) {
+                    try {
+                        await this._dreamScheduler.dispose();
+                    }
+                    catch { /* swallow during cleanup */ }
+                }
+                this._dreamScheduler = undefined;
+            }
+        }
         this._initialized = true;
     }
     async dispose() {
+        // ADR-094: Stop the dream scheduler first so a dream-in-progress doesn't
+        // try to write to a disposed memory backend.
+        if (this._dreamScheduler) {
+            try {
+                await this._dreamScheduler.dispose();
+            }
+            catch (err) {
+                console.warn('[QEKernel] DreamScheduler dispose failed:', err instanceof Error ? err.message : err);
+            }
+            this._dreamScheduler = undefined;
+        }
         // Stop the bridge first so it doesn't try to publish to a disposed bus.
         if (this._experienceBridge) {
             await this._experienceBridge.stop();

package/dist/kernel/unified-memory-schemas.d.ts

@@ -17,6 +17,6 @@ export declare const QE_PATTERNS_SCHEMA = "\n  -- QE Patterns table (unified fro
 export declare const MINCUT_SCHEMA = "\n  -- MinCut Graph Snapshots (ADR-047)\n  CREATE TABLE IF NOT EXISTS mincut_snapshots (\n    id TEXT PRIMARY KEY,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    vertex_count INTEGER NOT NULL,\n    edge_count INTEGER NOT NULL,\n    total_weight REAL NOT NULL DEFAULT 0.0,\n    is_connected INTEGER NOT NULL DEFAULT 1,\n    component_count INTEGER NOT NULL DEFAULT 1,\n    vertices_json TEXT NOT NULL,\n    edges_json TEXT NOT NULL,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n\n  -- MinCut History (time-series MinCut values)\n  CREATE TABLE IF NOT EXISTS mincut_history (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    mincut_value REAL NOT NULL,\n    vertex_count INTEGER NOT NULL,\n    edge_count INTEGER NOT NULL,\n    algorithm TEXT NOT NULL DEFAULT 'weighted-degree',\n    duration_ms INTEGER,\n    snapshot_id TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Weak Vertices (detected bottlenecks)\n  CREATE TABLE IF NOT EXISTS mincut_weak_vertices (\n    id TEXT PRIMARY KEY,\n    vertex_id TEXT NOT NULL,\n    weighted_degree REAL NOT NULL,\n    risk_score REAL NOT NULL,\n    reason TEXT NOT NULL,\n    domain TEXT,\n    vertex_type TEXT NOT NULL,\n    suggestions_json TEXT,\n    detected_at TEXT NOT NULL DEFAULT (datetime('now')),\n    resolved_at TEXT,\n    snapshot_id TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Alerts\n  CREATE TABLE IF NOT EXISTS mincut_alerts (\n    id TEXT PRIMARY KEY,\n    severity TEXT NOT NULL,\n    message TEXT NOT NULL,\n    mincut_value REAL NOT NULL,\n    threshold REAL NOT NULL,\n    affected_vertices_json TEXT,\n    remediations_json TEXT,\n    acknowledged INTEGER DEFAULT 0,\n    acknowledged_at TEXT,\n    acknowledged_by TEXT,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n\n  -- MinCut Healing Actions (self-healing history)\n  CREATE TABLE IF NOT EXISTS mincut_healing_actions (\n    id TEXT PRIMARY KEY,\n    action_type TEXT NOT NULL,\n    action_params_json TEXT NOT NULL,\n    success INTEGER NOT NULL,\n    mincut_before REAL NOT NULL,\n    mincut_after REAL NOT NULL,\n    improvement REAL NOT NULL DEFAULT 0.0,\n    error_message TEXT,\n    duration_ms INTEGER NOT NULL,\n    triggered_by TEXT,\n    snapshot_before_id TEXT,\n    snapshot_after_id TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_before_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL,\n    FOREIGN KEY (snapshot_after_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Strange Loop Observations (P1: self-organizing)\n  CREATE TABLE IF NOT EXISTS mincut_observations (\n    id TEXT PRIMARY KEY,\n    iteration INTEGER NOT NULL,\n    mincut_value REAL NOT NULL,\n    weak_vertex_count INTEGER NOT NULL DEFAULT 0,\n    weak_vertices_json TEXT,\n    snapshot_id TEXT,\n    prediction_json TEXT,\n    actual_vs_predicted_diff REAL,\n    timestamp TEXT NOT NULL DEFAULT (datetime('now')),\n    FOREIGN KEY (snapshot_id) REFERENCES mincut_snapshots(id) ON DELETE SET NULL\n  );\n\n  -- MinCut Indexes\n  CREATE INDEX IF NOT EXISTS idx_mincut_history_timestamp ON mincut_history(timestamp DESC);\n  CREATE INDEX IF NOT EXISTS idx_mincut_history_value ON mincut_history(mincut_value);\n  CREATE INDEX IF NOT EXISTS idx_mincut_weak_vertex ON mincut_weak_vertices(vertex_id);\n  CREATE INDEX IF NOT EXISTS idx_mincut_weak_risk ON mincut_weak_vertices(risk_score DESC);\n  CREATE INDEX IF NOT EXISTS idx_mincut_weak_resolved ON mincut_weak_vertices(resolved_at);\n  CREATE INDEX IF NOT EXISTS idx_mincut_alerts_severity ON mincut_alerts(severity);\n  CREATE INDEX IF NOT EXISTS idx_mincut_alerts_ack ON mincut_alerts(acknowledged);\n  CREATE INDEX IF NOT EXISTS idx_mincut_healing_type ON mincut_healing_actions(action_type);\n  CREATE INDEX IF NOT EXISTS idx_mincut_healing_success ON mincut_healing_actions(success);\n  CREATE INDEX IF NOT EXISTS idx_mincut_observations_iter ON mincut_observations(iteration);\n";
 export declare const SONA_PATTERNS_SCHEMA = "\n  -- SONA Patterns table (ADR-046: Pattern Persistence for Neural Backbone)\n  CREATE TABLE IF NOT EXISTS sona_patterns (\n    id TEXT PRIMARY KEY,\n    type TEXT NOT NULL,\n    domain TEXT NOT NULL,\n    state_embedding BLOB,\n    action_embedding BLOB,\n    action_type TEXT NOT NULL,\n    action_value TEXT,\n    outcome_reward REAL NOT NULL DEFAULT 0.0,\n    outcome_success INTEGER NOT NULL DEFAULT 0,\n    outcome_quality REAL NOT NULL DEFAULT 0.0,\n    confidence REAL DEFAULT 0.5,\n    usage_count INTEGER DEFAULT 0,\n    success_count INTEGER DEFAULT 0,\n    failure_count INTEGER DEFAULT 0,\n    metadata TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    updated_at TEXT DEFAULT (datetime('now')),\n    last_used_at TEXT\n  );\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_type ON sona_patterns(type);\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_domain ON sona_patterns(domain);\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_confidence ON sona_patterns(confidence DESC);\n  CREATE INDEX IF NOT EXISTS idx_sona_patterns_updated ON sona_patterns(updated_at DESC);\n";
 export declare const WITNESS_CHAIN_SCHEMA = "\n  -- Witness Chain (ADR-070: Cryptographic audit trail for QE decisions)\n  CREATE TABLE IF NOT EXISTS witness_chain (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    prev_hash TEXT NOT NULL,\n    action_hash TEXT NOT NULL,\n    action_type TEXT NOT NULL,\n    action_data TEXT,\n    timestamp TEXT NOT NULL,\n    actor TEXT NOT NULL\n  );\n  CREATE INDEX IF NOT EXISTS idx_witness_action_type ON witness_chain(action_type);\n  CREATE INDEX IF NOT EXISTS idx_witness_timestamp ON witness_chain(timestamp);\n";
-export declare const FEEDBACK_SCHEMA = "\n  -- Test outcomes (ADR-023: Quality Feedback Loop)\n  CREATE TABLE IF NOT EXISTS test_outcomes (\n    id TEXT PRIMARY KEY,\n    test_id TEXT NOT NULL,\n    test_name TEXT NOT NULL,\n    generated_by TEXT NOT NULL,\n    pattern_id TEXT,\n    framework TEXT NOT NULL,\n    language TEXT NOT NULL,\n    domain TEXT NOT NULL,\n    passed INTEGER NOT NULL,\n    error_message TEXT,\n    coverage_lines REAL DEFAULT 0,\n    coverage_branches REAL DEFAULT 0,\n    coverage_functions REAL DEFAULT 0,\n    mutation_score REAL,\n    execution_time_ms REAL NOT NULL,\n    flaky INTEGER DEFAULT 0,\n    flakiness_score REAL,\n    maintainability_score REAL NOT NULL,\n    complexity REAL,\n    lines_of_code INTEGER,\n    assertion_count INTEGER,\n    file_path TEXT,\n    source_file_path TEXT,\n    metadata_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_pattern ON test_outcomes(pattern_id);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_agent ON test_outcomes(generated_by);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_domain ON test_outcomes(domain);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_created ON test_outcomes(created_at);\n\n  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json)\n  CREATE TABLE IF NOT EXISTS routing_outcomes (\n    id TEXT PRIMARY KEY,\n    task_json TEXT NOT NULL,\n    decision_json TEXT NOT NULL,\n    used_agent TEXT NOT NULL,\n    followed_recommendation INTEGER NOT NULL,\n    success INTEGER NOT NULL,\n    quality_score REAL NOT NULL,\n    duration_ms REAL NOT NULL,\n    error TEXT,\n    model_tier TEXT,\n    advisor_consultation_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_agent ON routing_outcomes(used_agent);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_created ON routing_outcomes(created_at);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_tier ON routing_outcomes(model_tier);\n\n  -- Coverage sessions (ADR-023: Coverage Learning)\n  CREATE TABLE IF NOT EXISTS coverage_sessions (\n    id TEXT PRIMARY KEY,\n    target_path TEXT NOT NULL,\n    agent_id TEXT NOT NULL,\n    technique TEXT NOT NULL,\n    before_lines REAL DEFAULT 0,\n    before_branches REAL DEFAULT 0,\n    before_functions REAL DEFAULT 0,\n    after_lines REAL DEFAULT 0,\n    after_branches REAL DEFAULT 0,\n    after_functions REAL DEFAULT 0,\n    tests_generated INTEGER DEFAULT 0,\n    tests_passed INTEGER DEFAULT 0,\n    gaps_json TEXT,\n    duration_ms REAL NOT NULL,\n    started_at TEXT NOT NULL,\n    completed_at TEXT NOT NULL,\n    context_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_technique ON coverage_sessions(technique);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_agent ON coverage_sessions(agent_id);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_created ON coverage_sessions(created_at);\n";
+export declare const FEEDBACK_SCHEMA = "\n  -- Test outcomes (ADR-023: Quality Feedback Loop)\n  CREATE TABLE IF NOT EXISTS test_outcomes (\n    id TEXT PRIMARY KEY,\n    test_id TEXT NOT NULL,\n    test_name TEXT NOT NULL,\n    generated_by TEXT NOT NULL,\n    pattern_id TEXT,\n    framework TEXT NOT NULL,\n    language TEXT NOT NULL,\n    domain TEXT NOT NULL,\n    passed INTEGER NOT NULL,\n    error_message TEXT,\n    coverage_lines REAL DEFAULT 0,\n    coverage_branches REAL DEFAULT 0,\n    coverage_functions REAL DEFAULT 0,\n    mutation_score REAL,\n    execution_time_ms REAL NOT NULL,\n    flaky INTEGER DEFAULT 0,\n    flakiness_score REAL,\n    maintainability_score REAL NOT NULL,\n    complexity REAL,\n    lines_of_code INTEGER,\n    assertion_count INTEGER,\n    file_path TEXT,\n    source_file_path TEXT,\n    metadata_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_pattern ON test_outcomes(pattern_id);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_agent ON test_outcomes(generated_by);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_domain ON test_outcomes(domain);\n  CREATE INDEX IF NOT EXISTS idx_test_outcomes_created ON test_outcomes(created_at);\n\n  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json,\n  -- ADR-095: exploration / criticality / q_weight for \u03B5-greedy routing telemetry)\n  CREATE TABLE IF NOT EXISTS routing_outcomes (\n    id TEXT PRIMARY KEY,\n    task_json TEXT NOT NULL,\n    decision_json TEXT NOT NULL,\n    used_agent TEXT NOT NULL,\n    followed_recommendation INTEGER NOT NULL,\n    success INTEGER NOT NULL,\n    quality_score REAL NOT NULL,\n    duration_ms REAL NOT NULL,\n    error TEXT,\n    model_tier TEXT,\n    advisor_consultation_json TEXT,\n    -- ADR-095: routing exploration telemetry\n    exploration INTEGER NOT NULL DEFAULT 0,\n    criticality REAL,\n    q_weight REAL,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_agent ON routing_outcomes(used_agent);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_created ON routing_outcomes(created_at);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_tier ON routing_outcomes(model_tier);\n  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_exploration ON routing_outcomes(exploration);\n\n  -- Coverage sessions (ADR-023: Coverage Learning)\n  CREATE TABLE IF NOT EXISTS coverage_sessions (\n    id TEXT PRIMARY KEY,\n    target_path TEXT NOT NULL,\n    agent_id TEXT NOT NULL,\n    technique TEXT NOT NULL,\n    before_lines REAL DEFAULT 0,\n    before_branches REAL DEFAULT 0,\n    before_functions REAL DEFAULT 0,\n    after_lines REAL DEFAULT 0,\n    after_branches REAL DEFAULT 0,\n    after_functions REAL DEFAULT 0,\n    tests_generated INTEGER DEFAULT 0,\n    tests_passed INTEGER DEFAULT 0,\n    gaps_json TEXT,\n    duration_ms REAL NOT NULL,\n    started_at TEXT NOT NULL,\n    completed_at TEXT NOT NULL,\n    context_json TEXT,\n    created_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_technique ON coverage_sessions(technique);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_agent ON coverage_sessions(agent_id);\n  CREATE INDEX IF NOT EXISTS idx_coverage_sessions_created ON coverage_sessions(created_at);\n";
 export declare const STATS_TABLES: string[];
 //# sourceMappingURL=unified-memory-schemas.d.ts.map

package/dist/kernel/unified-memory-schemas.js

@@ -540,7 +540,8 @@ export const FEEDBACK_SCHEMA = `
   CREATE INDEX IF NOT EXISTS idx_test_outcomes_domain ON test_outcomes(domain);
   CREATE INDEX IF NOT EXISTS idx_test_outcomes_created ON test_outcomes(created_at);
 
-  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json)
+  -- Routing outcomes (ADR-022: Adaptive QE Agent Routing, ADR-092: advisor_consultation_json,
+  -- ADR-095: exploration / criticality / q_weight for ε-greedy routing telemetry)
   CREATE TABLE IF NOT EXISTS routing_outcomes (
     id TEXT PRIMARY KEY,
     task_json TEXT NOT NULL,
@@ -553,11 +554,16 @@ export const FEEDBACK_SCHEMA = `
     error TEXT,
     model_tier TEXT,
     advisor_consultation_json TEXT,
+    -- ADR-095: routing exploration telemetry
+    exploration INTEGER NOT NULL DEFAULT 0,
+    criticality REAL,
+    q_weight REAL,
     created_at TEXT DEFAULT (datetime('now'))
   );
   CREATE INDEX IF NOT EXISTS idx_routing_outcomes_agent ON routing_outcomes(used_agent);
   CREATE INDEX IF NOT EXISTS idx_routing_outcomes_created ON routing_outcomes(created_at);
   CREATE INDEX IF NOT EXISTS idx_routing_outcomes_tier ON routing_outcomes(model_tier);
+  CREATE INDEX IF NOT EXISTS idx_routing_outcomes_exploration ON routing_outcomes(exploration);
 
   -- Coverage sessions (ADR-023: Coverage Learning)
   CREATE TABLE IF NOT EXISTS coverage_sessions (

package/dist/learning/agent-routing.d.ts

@@ -1,6 +1,7 @@
 /**
  * Agentic QE v3 - Agent Routing
  * ADR-021: QE ReasoningBank for Pattern Learning
+ * ADR-095: ε-greedy exploration with Q-value blending and mincut safety gate
  *
  * Static agent capability mapping and routing score calculation
  * used by QEReasoningBank.routeTask().
@@ -22,11 +23,28 @@ export interface AgentCapabilityProfile {
 export declare const AGENT_CAPABILITIES: Record<string, AgentCapabilityProfile>;
 /**
  * Scored agent with reasoning trace.
+ *
+ * ADR-095 telemetry fields (all optional, populated only when the
+ * corresponding signal source is wired):
+ *   - `staticScore`: the pre-blend score (domain + capability + perf + …)
+ *   - `qWeight`, `qValue`: when Q-table data was available
+ *   - `exploration`: true if this agent was promoted to position 0 by the
+ *     ε-greedy policy rather than scored to the top deterministically
  */
 export interface ScoredAgent {
     agent: string;
     score: number;
     reasoning: string[];
+    /** ADR-095: pre-blend static score for retrospective explainability */
+    staticScore?: number;
+    /** ADR-095: Q-value influence (0..MAX_Q_WEIGHT) on the final score */
+    qWeight?: number;
+    /** ADR-095: raw q_value from rl_q_values, for telemetry */
+    qValue?: number;
+    /** ADR-095: number of (state_key, action_key) visits behind the Q value */
+    qVisits?: number;
+    /** ADR-095: true when ε-greedy promoted this agent over the greedy winner */
+    exploration?: boolean;
 }
 /**
  * Routing weight configuration.
@@ -38,6 +56,114 @@ export interface RoutingWeights {
     /** Weight for language match boost (default: 1.0) */
     language?: number;
 }
+/**
+ * Maximum Q-value influence on the final score.
+ *
+ * 0.4 means a fully-mature Q-value can move the score by up to ±0.2 (since
+ * normalizedQ ranges over (0, 1) and the static contribution clamps the
+ * upper bound). This is intentionally bounded so Q-values inform rather
+ * than override the static features.
+ *
+ * Tuning: post-deploy telemetry will tell us whether agents are actually
+ * being separated by Q-values. If the avg `q_weight` in routing_outcomes
+ * climbs but quality_score doesn't improve, this constant is too high.
+ */
+export declare const MAX_Q_WEIGHT = 0.4;
+/**
+ * Number of (state_key, action_key) visits at which qWeight saturates at
+ * MAX_Q_WEIGHT. Below this, qWeight ramps linearly from 0.
+ *
+ * 20 visits at the default 30-min worker tick + typical session cadence
+ * implies ~1 week of activity before a (state, agent) pair drives the
+ * decision. Adjust downward if cold-start latency proves problematic.
+ */
+export declare const QWEIGHT_RAMP_VISITS = 20;
+/**
+ * Q-value lookup callback supplied by the caller (QEReasoningBank.routeTask).
+ * Returns undefined when the (stateKey, agentType) pair has no recorded
+ * Q-value yet — caller does not need to handle missing-row vs zero-visits.
+ */
+export type QValueLookup = (agentType: string) => {
+    qValue: number;
+    visits: number;
+} | undefined;
+/**
+ * Blend a static score with a Q-value contribution.
+ *
+ *   effectiveScore = staticScore * (1 - qWeight) + normalizedQ * qWeight
+ *
+ * Returns { score, qWeight, qValue, qVisits } so callers can attach the
+ * telemetry fields to the ScoredAgent record.
+ */
+export declare function blendStaticAndQValue(staticScore: number, qLookup: {
+    qValue: number;
+    visits: number;
+} | undefined): {
+    score: number;
+    qWeight: number;
+    qValue: number;
+    qVisits: number;
+};
+/**
+ * Resolve the per-decision ε for the exploration policy.
+ *
+ * Priority order:
+ *   1. AQE_ROUTER_EXPLORATION_RATE env var (operator override, fixed)
+ *   2. Default base rate (0.05)
+ * The result is then multiplied by the mincut safety gate (caller passes
+ * `topologyCritical` derived from getSharedMinCutMonitor().isCritical()):
+ * critical topology → 0.2x dampening, healthy/unknown → 1.0x.
+ *
+ * Returns a number in [0, 1].
+ */
+export declare function resolveExplorationRate(opts: {
+    envOverride?: string;
+    topologyCritical?: boolean;
+}): {
+    epsilon: number;
+    baseEpsilon: number;
+    safetyMultiplier: number;
+};
+/**
+ * Apply the ε-greedy exploration policy to a sorted score list.
+ *
+ * With probability ε (computed from resolveExplorationRate), swaps the
+ * top-scored agent with a uniformly-random pick from positions 1..3 (or
+ * fewer if the list is shorter). Mutates `agentScores` in place. The
+ * promoted agent gets `exploration = true`.
+ *
+ * Uses `crypto.randomInt` for cryptographically-strong uniform sampling —
+ * matches the codebase convention (randomUUID is imported from 'crypto'
+ * in the same modules). Math.random() would work but breaks consistency.
+ */
+export declare function applyExplorationPolicy(agentScores: ScoredAgent[], epsilon: number): void;
+/**
+ * Derive a structural taskType from a free-form task description. Used to
+ * build the q-learning state_key shared with the post-task Bellman update
+ * (hooks-dream-learning.ts).
+ *
+ * Exported (rather than kept private in task-hooks) so QEReasoningBank can
+ * compute the same state_key at routing time as post-task does at outcome
+ * time — without that, the Q-table writer and reader would address
+ * different keys.
+ */
+export declare function deriveTaskType(description: string): string;
+/**
+ * Build the canonical Q-learning state_key. Must match the format used by
+ * `updateHookRouterQValue` in hooks-dream-learning.ts — the writer and
+ * reader must agree on the key shape.
+ */
+export declare function buildRoutingStateKey(opts: {
+    taskType: string;
+    priority?: string;
+    domain?: string;
+    complexityBucket: number;
+}): string;
+/**
+ * Compute the complexity bucket [0, 10] from a task description length.
+ * Mirrors the formula in task-hooks.ts pre-task bridge.
+ */
+export declare function deriveComplexityBucket(description: string): number;
 /**
  * Calculate agent scores for a routing request.
  *
@@ -49,7 +175,14 @@ export interface RoutingWeights {
  * @param requestLanguage - Optional language to boost agents with matching language expertise
  * @returns Sorted array of scored agents (highest score first)
  */
-export declare function calculateAgentScores(detectedDomains: QEDomain[], requestCapabilities: string[] | undefined, agentDomainPatternCounts: Map<string, number>, routingWeights: RoutingWeights, agentCapabilities?: Record<string, AgentCapabilityProfile>, requestLanguage?: string): ScoredAgent[];
+export declare function calculateAgentScores(detectedDomains: QEDomain[], requestCapabilities: string[] | undefined, agentDomainPatternCounts: Map<string, number>, routingWeights: RoutingWeights, agentCapabilities?: Record<string, AgentCapabilityProfile>, requestLanguage?: string, 
+/**
+ * ADR-095: optional per-agent Q-value lookup. When provided, the static
+ * score is blended with the Q-value contribution via blendStaticAndQValue.
+ * When omitted (or returning undefined for every agent), behavior is
+ * identical to the pre-ADR-095 deterministic scoring.
+ */
+qValueLookup?: QValueLookup): ScoredAgent[];
 /**
  * Domain compatibility matrix for cross-domain pattern transfer.
  * Maps each domain to its related domains (same as TransferSpecialistService).