agentic-qe 3.11.0 → 3.11.2

package/dist/mcp/tool-scoping.d.ts

@@ -9,13 +9,19 @@ export type AgentRole = 'test-generator' | 'coverage-analyzer' | 'security-scann
  * Tool scope definition for an agent role
  */
 export interface ToolScope {
-    /** Tools the agent can use (if empty/undefined, uses allowAll) */
+    /**
+     * Tools the agent can use. DEFAULT-DENY: if this is empty/undefined and
+     * `allowAll` is not set, the role is denied EVERY tool (`isToolAllowed`
+     * falls through to `return false`). It does NOT grant allowAll.
+     */
     allowed?: string[];
     /** Tools explicitly denied (overrides allowed) */
     denied?: string[];
-    /** Allow all tools (default for fleet-admin and unrestricted) */
+    /** Allow all tools — admin tiers only (fleet-admin, unrestricted). */
     allowAll?: boolean;
 }
+/** Every agent role, in declaration order — for governance/policy iteration. */
+export declare const ALL_AGENT_ROLES: AgentRole[];
 /**
  * Check if an agent role is allowed to use a specific tool
  */

package/dist/mcp/tool-scoping.js

@@ -4,6 +4,19 @@
  * Restricts MCP tool access by agent role for security isolation.
  * Each agent type has a defined set of tools it can invoke.
  */
+/** Every agent role, in declaration order — for governance/policy iteration. */
+export const ALL_AGENT_ROLES = [
+    'test-generator',
+    'coverage-analyzer',
+    'security-scanner',
+    'quality-assessor',
+    'defect-predictor',
+    'contract-validator',
+    'accessibility-tester',
+    'chaos-engineer',
+    'fleet-admin',
+    'unrestricted',
+];
 /**
  * Default tool scopes per agent role
  */

package/dist/mcp/tools/code-intelligence/c4.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agentic QE v3 - C4 Architecture MCP Tool (ADR-112)
+ *
+ * qe/code/c4 - Generate C4 architecture diagrams (Context/Container/Component,
+ * Mermaid) from codebase analysis, plus semantic search over stored diagrams.
+ *
+ * Wraps the SAME pipeline the CLI `aqe code c4` drives:
+ *   ProductFactorsBridgeService (detect) → C4ModelService (render+store) →
+ *   deterministic confidence gate. This keeps MCP-CLI parity by construction.
+ */
+import { MCPToolBase, MCPToolConfig, MCPToolContext } from '../base';
+import { ToolResult } from '../../types';
+import type { C4Diagrams, C4ConfidenceAssessment } from '../../../shared/c4-model';
+export type C4Level = 'context' | 'container' | 'component' | 'all';
+export interface CodeC4Params {
+    action: 'generate' | 'search';
+    projectPath?: string;
+    level?: C4Level;
+    query?: string;
+    limit?: number;
+    [key: string]: unknown;
+}
+export interface C4GenerateResult {
+    diagrams: C4Diagrams;
+    confidence?: C4ConfidenceAssessment;
+    componentsDetected: number;
+    externalSystemsDetected: number;
+    relationshipsDetected: number;
+    circularDependencies: number;
+}
+export interface C4SearchHit {
+    key: string;
+    type: 'context' | 'container' | 'component';
+    title: string;
+    score: number;
+    preview: string;
+}
+export interface C4SearchResult {
+    results: C4SearchHit[];
+    total: number;
+}
+export interface CodeC4Result {
+    action: string;
+    generateResult?: C4GenerateResult;
+    searchResult?: C4SearchResult;
+}
+export declare class CodeC4Tool extends MCPToolBase<CodeC4Params, CodeC4Result> {
+    readonly config: MCPToolConfig;
+    private bridge;
+    private searchService;
+    private getBridge;
+    /** Embeddings ON here so stored diagrams are semantically searchable. */
+    private getSearchService;
+    execute(params: CodeC4Params, context: MCPToolContext): Promise<ToolResult<CodeC4Result>>;
+}
+//# sourceMappingURL=c4.d.ts.map

package/dist/mcp/tools/code-intelligence/c4.js

@@ -0,0 +1,145 @@
+/**
+ * Agentic QE v3 - C4 Architecture MCP Tool (ADR-112)
+ *
+ * qe/code/c4 - Generate C4 architecture diagrams (Context/Container/Component,
+ * Mermaid) from codebase analysis, plus semantic search over stored diagrams.
+ *
+ * Wraps the SAME pipeline the CLI `aqe code c4` drives:
+ *   ProductFactorsBridgeService (detect) → C4ModelService (render+store) →
+ *   deterministic confidence gate. This keeps MCP-CLI parity by construction.
+ */
+import { MCPToolBase, getSharedMemoryBackend } from '../base';
+import { ProductFactorsBridgeService } from '../../../domains/code-intelligence/services/product-factors-bridge';
+import { C4ModelService } from '../../../domains/code-intelligence/services/c4-model';
+import { KnowledgeGraphService } from '../../../domains/code-intelligence/services/knowledge-graph';
+import { createKnowledgeGraphRelationshipResolver } from '../../../domains/code-intelligence/services/c4-model/kg-relationships';
+import { InMemoryEventBus } from '../../../kernel/event-bus';
+import { toErrorMessage } from '../../../shared/error-utils.js';
+const want = (level, l) => level === 'all' || level === l;
+// ============================================================================
+// Tool Implementation
+// ============================================================================
+export class CodeC4Tool extends MCPToolBase {
+    config = {
+        name: 'qe/code/c4',
+        description: 'Generate C4 architecture diagrams (Context/Container/Component, Mermaid) from a codebase with a deterministic confidence gate, or semantically search previously generated diagrams.',
+        domain: 'code-intelligence',
+        schema: CODE_C4_SCHEMA,
+        streaming: false,
+        timeout: 300000,
+    };
+    bridge = null;
+    searchService = null;
+    async getBridge(context) {
+        if (!this.bridge) {
+            const memory = context.memory ?? (await getSharedMemoryBackend());
+            // ADR-112 C2: KG-backed resolver (project-scoped) so MCP matches the CLI.
+            // publishEvents:false — the MCP path doesn't need the cross-domain event.
+            this.bridge = new ProductFactorsBridgeService(new InMemoryEventBus(), memory, {
+                publishEvents: false,
+                // ADR-112: embed generated diagrams so `search` can find them.
+                enableC4Embeddings: true,
+                relationshipResolver: createKnowledgeGraphRelationshipResolver((projectPath) => new KnowledgeGraphService(memory, { basePath: projectPath })),
+            });
+        }
+        return this.bridge;
+    }
+    /** Embeddings ON here so stored diagrams are semantically searchable. */
+    async getSearchService(context) {
+        if (!this.searchService) {
+            const memory = context.memory ?? (await getSharedMemoryBackend());
+            this.searchService = new C4ModelService(memory, { enableEmbeddings: true });
+        }
+        return this.searchService;
+    }
+    async execute(params, context) {
+        const { action, projectPath = '.', level = 'all', query, limit = 10 } = params;
+        try {
+            if (this.isAborted(context)) {
+                return { success: false, error: 'Operation aborted' };
+            }
+            const result = { action };
+            switch (action) {
+                case 'generate': {
+                    const bridge = await this.getBridge(context);
+                    const res = await bridge.requestC4Diagrams({
+                        projectPath,
+                        includeContext: want(level, 'context'),
+                        includeContainer: want(level, 'container'),
+                        includeComponent: want(level, 'component'),
+                        includeDependency: level === 'all',
+                        analyzeComponents: true,
+                        detectExternalSystems: true,
+                        analyzeCoupling: true,
+                    });
+                    if (!res.success) {
+                        return { success: false, error: toErrorMessage(res.error) };
+                    }
+                    const c4 = res.value;
+                    result.generateResult = {
+                        diagrams: c4.diagrams,
+                        confidence: c4.metadata.analysisMetadata?.confidence,
+                        componentsDetected: c4.components.length,
+                        externalSystemsDetected: c4.externalSystems.length,
+                        relationshipsDetected: c4.relationships.length,
+                        circularDependencies: (c4.couplingAnalysis ?? []).filter((co) => co.isCircular).length,
+                    };
+                    break;
+                }
+                case 'search': {
+                    if (!query) {
+                        return { success: false, error: 'Query is required for search action' };
+                    }
+                    const service = await this.getSearchService(context);
+                    const res = await service.searchDiagrams(query, limit);
+                    if (!res.success) {
+                        return { success: false, error: toErrorMessage(res.error) };
+                    }
+                    result.searchResult = {
+                        results: res.value.map((r) => ({ key: r.key, type: r.type, title: r.title, score: r.score, preview: r.preview })),
+                        total: res.value.length,
+                    };
+                    break;
+                }
+                default:
+                    return { success: false, error: `Unknown action: ${action}` };
+            }
+            return { success: true, data: result };
+        }
+        catch (error) {
+            return { success: false, error: toErrorMessage(error) };
+        }
+    }
+}
+// ============================================================================
+// Schema
+// ============================================================================
+const CODE_C4_SCHEMA = {
+    type: 'object',
+    properties: {
+        action: {
+            type: 'string',
+            description: 'C4 action to perform',
+            enum: ['generate', 'search'],
+        },
+        projectPath: {
+            type: 'string',
+            description: 'Project root to analyze (generate action). Defaults to the current directory.',
+        },
+        level: {
+            type: 'string',
+            description: 'C4 level to generate (generate action)',
+            enum: ['context', 'container', 'component', 'all'],
+        },
+        query: {
+            type: 'string',
+            description: 'Semantic search query over stored diagrams (search action)',
+        },
+        limit: {
+            type: 'number',
+            description: 'Max search results (search action)',
+        },
+    },
+    required: ['action'],
+};
+//# sourceMappingURL=c4.js.map

package/dist/mcp/tools/index.d.ts

@@ -37,6 +37,7 @@ export { DefectPredictTool, type DefectPredictParams, type DefectPredictResult,
 export { RequirementsValidateTool, type RequirementsValidateParams, type RequirementsValidateResult, type RequirementInput, type ValidationResult, type TestabilityScore, type BDDScenario, } from './requirements-validation/validate';
 export { QualityCriteriaTool, qualityCriteriaTool, type QualityCriteriaParams, type QualityCriteriaResult, type EvidencePointInput, type AgentInvocation, } from './requirements-validation/quality-criteria';
 export { CodeAnalyzeTool, type CodeAnalyzeParams, type CodeAnalyzeResult, type IndexResult, type SearchResult, type ImpactResult, type DependencyResult, } from './code-intelligence/analyze';
+export { CodeC4Tool, type CodeC4Params, type CodeC4Result, type C4GenerateResult, type C4SearchResult, } from './code-intelligence/c4';
 export { SecurityScanTool, type SecurityScanParams, type SecurityScanResult, type Vulnerability, type ScanSummary, type ComplianceResult, } from './security-compliance/scan';
 export { ContractValidateTool, type ContractValidateParams, type ContractValidateResult, type BreakingChange, type VerificationResult, type CompatibilityReport, } from './contract-testing/validate';
 export { VisualCompareTool, A11yAuditTool, type VisualCompareParams, type VisualCompareResult, type A11yAuditParams, type A11yAuditResult, type A11yViolation, type VisualComparison, } from './visual-accessibility';

package/dist/mcp/tools/index.js

@@ -61,6 +61,7 @@ export { QualityCriteriaTool, qualityCriteriaTool, } from './requirements-valida
 // Code Intelligence Domain
 // ============================================================================
 export { CodeAnalyzeTool, } from './code-intelligence/analyze';
+export { CodeC4Tool, } from './code-intelligence/c4';
 // ============================================================================
 // Security Compliance Domain
 // ============================================================================

package/dist/mcp/tools/registry.d.ts

@@ -33,6 +33,7 @@ export declare const QE_TOOL_NAMES: {
     readonly REQUIREMENTS_VALIDATE: "qe/requirements/validate";
     readonly QUALITY_CRITERIA: "qe/requirements/quality-criteria";
     readonly CODE_ANALYZE: "qe/code/analyze";
+    readonly CODE_C4: "qe/code/c4";
     readonly SECURITY_SCAN: "qe/security/scan";
     readonly CONTRACT_VALIDATE: "qe/contracts/validate";
     readonly VISUAL_COMPARE: "qe/visual/compare";

package/dist/mcp/tools/registry.js

@@ -13,6 +13,7 @@ import { DefectPredictTool } from './defect-intelligence/predict';
 import { RequirementsValidateTool } from './requirements-validation/validate';
 import { QualityCriteriaTool } from './requirements-validation/quality-criteria';
 import { CodeAnalyzeTool } from './code-intelligence/analyze';
+import { CodeC4Tool } from './code-intelligence/c4';
 import { SecurityScanTool } from './security-compliance/scan';
 import { ContractValidateTool } from './contract-testing/validate';
 import { VisualCompareTool, A11yAuditTool } from './visual-accessibility';
@@ -48,6 +49,7 @@ export const QE_TOOL_NAMES = {
     QUALITY_CRITERIA: 'qe/requirements/quality-criteria',
     // Code Intelligence
     CODE_ANALYZE: 'qe/code/analyze',
+    CODE_C4: 'qe/code/c4',
     // Security Compliance
     SECURITY_SCAN: 'qe/security/scan',
     // Contract Testing
@@ -110,6 +112,7 @@ export const QE_TOOLS = [
     new QualityCriteriaTool(),
     // Code Intelligence Domain
     new CodeAnalyzeTool(),
+    new CodeC4Tool(),
     // Security Compliance Domain
     new SecurityScanTool(),
     // Contract Testing Domain

package/dist/routing/free-tier/coordinator-support.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Coordinator free-tier support (cross-pollination plan 06 — broadening the
+ * opt-in beyond test generation; ADR-111 escalation lane).
+ *
+ * Extracts the generic "build a FreeTierEscalatingExecutor from a coordinator's
+ * config + router" wiring that was inline in the test-generation coordinator, so
+ * ANY domain coordinator can opt in with a few lines instead of duplicating it.
+ *
+ * The opt-in lane is justified only for tasks that match the D3 criterion:
+ * BOUNDED generation graded by an OBJECTIVE oracle (a test+assertion, valid
+ * Gherkin, a schema). Do NOT wire it into analysis/judgement coordinators — the
+ * §11 "coder binds" finding means a cheap model can't carry open-ended reasoning.
+ */
+import { FreeTierEscalatingExecutor, type QeExecutionResult, type QeVerifier } from './executor.js';
+import { type RoutingFeedbackLike } from './feedback-sink.js';
+import type { FreeTierProviderConfig } from './types.js';
+/** Default cheap tier. qwen3:30b-a3b, NOT qwen3:8b — D3 (2026-06-23) measured the
+ *  8B below the QE generation floor (0/3 baseline-valid); the 30B MoE clears it. */
+export declare const DEFAULT_FREE_TIER_MODEL = "qwen3:30b-a3b";
+/** Per-coordinator config knobs (mix into a coordinator's CoordinatorConfig). */
+export interface FreeTierCoordinatorConfig {
+    /** Opt-in the cheap-first free local tier. Also via env `AQE_FREE_TIER=1`. */
+    enableFreeTier?: boolean;
+    /** Local model id (default {@link DEFAULT_FREE_TIER_MODEL} or env AQE_FREE_TIER_MODEL). */
+    freeTierModel?: string;
+    /** Default same-tier D8 repair retries before escalating. Benchmarked at 2 (D3). */
+    freeTierRepairAttempts?: number;
+    /**
+     * Best-of-k diverse attempts per tier's first round (06 §12). D3 validated k=2
+     * (lifted cheap composite +16.7, baseline-valid 50%→70%). Costs an extra local
+     * call ONLY when variant 0 fails (the loop breaks on first pass). Default 2.
+     */
+    freeTierBestOfK?: number;
+    /**
+     * Cross-model best-of-k generator pool (A12, measured +6 composite over single-
+     * model via mutual validity rescue). When set, round-0 best-of-k draws candidates
+     * across these providers (e.g. local qwen + an OpenRouter model) instead of one
+     * model's variants. Omit ⇒ single-model. Set `freeTierBestOfK ≥ pool size`.
+     */
+    freeTierCandidateProviders?: FreeTierProviderConfig[];
+}
+/** Structural view of the HybridRouter — avoids a hard import (decoupling). */
+export interface FreeTierLlmRouter {
+    chat(args: {
+        messages: Array<{
+            role: 'system' | 'user' | 'assistant';
+            content: string;
+        }>;
+        agentType: string;
+        complexity: 'low' | 'medium' | 'high';
+    }): Promise<{
+        content: string;
+    }>;
+}
+export interface BuildFreeTierExecutorOptions {
+    config: FreeTierCoordinatorConfig;
+    /** Router agentType hint for escalated (paid) tiers, e.g. 'qe-test-architect'. */
+    agentType: string;
+    /** D9 sink label, e.g. 'test-generation'. */
+    taskKind: string;
+    /** Delegate Claude tiers to the host router; omit → local-only (no escalation). */
+    llmRouter?: FreeTierLlmRouter | null;
+    /** D9: feed cheap-vs-escalated outcomes into routing-feedback. */
+    routingFeedback?: RoutingFeedbackLike | null;
+    env?: NodeJS.ProcessEnv;
+    logger?: {
+        info: (m: string) => void;
+    };
+}
+/**
+ * Build a cheap-first escalating executor from coordinator config + (optional)
+ * router. Returns `null` when the free tier is not opted in — callers store the
+ * result and fall through to their normal path when it is null.
+ */
+export declare function buildFreeTierExecutor(opts: BuildFreeTierExecutorOptions): FreeTierEscalatingExecutor | null;
+/**
+ * Run one bounded generation task cheap-first: best-of-k diverse attempts +
+ * D8 repair on the local tier, escalating the hard tail. Returns `null` when no
+ * executor (not opted in). The `verify` MUST be an objective oracle (06 §10).
+ */
+export declare function runFreeTierTextTask(executor: FreeTierEscalatingExecutor | null, args: {
+    agentId: string;
+    system: string;
+    user: string;
+    verify: QeVerifier;
+    repairAttempts?: number;
+    escalate?: boolean;
+    bestOfK?: number;
+}): Promise<QeExecutionResult | null>;
+//# sourceMappingURL=coordinator-support.d.ts.map

package/dist/routing/free-tier/coordinator-support.js

@@ -0,0 +1,78 @@
+/**
+ * Coordinator free-tier support (cross-pollination plan 06 — broadening the
+ * opt-in beyond test generation; ADR-111 escalation lane).
+ *
+ * Extracts the generic "build a FreeTierEscalatingExecutor from a coordinator's
+ * config + router" wiring that was inline in the test-generation coordinator, so
+ * ANY domain coordinator can opt in with a few lines instead of duplicating it.
+ *
+ * The opt-in lane is justified only for tasks that match the D3 criterion:
+ * BOUNDED generation graded by an OBJECTIVE oracle (a test+assertion, valid
+ * Gherkin, a schema). Do NOT wire it into analysis/judgement coordinators — the
+ * §11 "coder binds" finding means a cheap model can't carry open-ended reasoning.
+ */
+import { FreeTierEscalatingExecutor } from './executor.js';
+import { defaultFreeTierLadder } from './ladder.js';
+import { createRoutingFeedbackSink } from './feedback-sink.js';
+/** Default cheap tier. qwen3:30b-a3b, NOT qwen3:8b — D3 (2026-06-23) measured the
+ *  8B below the QE generation floor (0/3 baseline-valid); the 30B MoE clears it. */
+export const DEFAULT_FREE_TIER_MODEL = 'qwen3:30b-a3b';
+/**
+ * Build a cheap-first escalating executor from coordinator config + (optional)
+ * router. Returns `null` when the free tier is not opted in — callers store the
+ * result and fall through to their normal path when it is null.
+ */
+export function buildFreeTierExecutor(opts) {
+    const env = opts.env ?? process.env;
+    const on = opts.config.enableFreeTier === true || env.AQE_FREE_TIER === '1';
+    if (!on)
+        return null;
+    const model = opts.config.freeTierModel || env.AQE_FREE_TIER_MODEL || DEFAULT_FREE_TIER_MODEL;
+    // Paid escalation: map the ladder tier to a complexity hint so the host router
+    // picks that tier. No router → executor stays local-only (Claude tiers unavailable).
+    const claudeRunner = opts.llmRouter
+        ? async (tier, msgs) => {
+            const complexity = tier === 'opus' ? 'high' : tier === 'sonnet' ? 'medium' : 'low';
+            const resp = await opts.llmRouter.chat({
+                messages: msgs.map((m) => ({ role: m.role, content: m.content })),
+                agentType: opts.agentType,
+                complexity,
+            });
+            return { content: resp.content };
+        }
+        : undefined;
+    const exec = new FreeTierEscalatingExecutor({
+        ladder: defaultFreeTierLadder(model),
+        claudeRunner,
+        defaultRepairAttempts: opts.config.freeTierRepairAttempts ?? 1,
+        candidateProviders: opts.config.freeTierCandidateProviders, // A12 cross-model (off unless set)
+        onOutcome: opts.routingFeedback
+            ? createRoutingFeedbackSink(opts.routingFeedback, { taskKind: opts.taskKind })
+            : undefined,
+    });
+    opts.logger?.info(`Free-tier enabled for ${opts.taskKind} (model=${model}, ` +
+        `${claudeRunner ? 'escalation→router' : 'local-only'})`);
+    return exec;
+}
+/**
+ * Run one bounded generation task cheap-first: best-of-k diverse attempts +
+ * D8 repair on the local tier, escalating the hard tail. Returns `null` when no
+ * executor (not opted in). The `verify` MUST be an objective oracle (06 §10).
+ */
+export async function runFreeTierTextTask(executor, args) {
+    if (!executor)
+        return null;
+    return executor.execute({
+        agentId: args.agentId,
+        messages: [
+            { role: 'system', content: args.system },
+            { role: 'user', content: args.user },
+        ],
+        verify: args.verify,
+        repairAttempts: args.repairAttempts,
+        escalate: args.escalate ?? true,
+        bestOfK: args.bestOfK,
+        oracleKind: 'objective',
+    });
+}
+//# sourceMappingURL=coordinator-support.js.map

package/dist/routing/free-tier/executor.d.ts

@@ -16,7 +16,7 @@
  */
 import { type ChatMessage } from './provider.js';
 import { AutoEscalationTracker } from '../escalation/auto-escalation-tracker.js';
-import type { QeRoutingLadder } from './types.js';
+import type { QeRoutingLadder, FreeTierProviderConfig } from './types.js';
 import type { AgentTier } from '../routing-config.js';
 /** Serves a Claude tier. Injected by the host (e.g. delegates to HybridRouter). */
 export type ClaudeTierRunner = (claudeTier: AgentTier, messages: ChatMessage[]) => Promise<{
@@ -43,12 +43,30 @@ export interface QeTaskRequest {
     escalate?: boolean;
     /** Cap on tiers tried for one task (default: full ladder). */
     maxEscalations?: number;
+    /**
+     * Best-of-k diverse attempts at each tier's first round (06 §12 correction).
+     * Ruv's ablation: a single repro-gated shot Goodharts the oracle (0 gold); k>1
+     * diverse attempts picked by the objective verifier are what convert. Default 1.
+     */
+    bestOfK?: number;
+    /**
+     * Goodhart guard (06 §10). `objective` = the verifier is a deterministic
+     * ground-truth oracle (arena/coverage/schema). `self-authored` = the verifier
+     * is the model's own test — an unreliable selection target, so its outcomes are
+     * NOT recorded into routing-feedback (they must not lift confidence). Default
+     * `objective` (existing callers inject real oracles, e.g. a coverage/test run).
+     */
+    oracleKind?: 'objective' | 'self-authored';
 }
 export interface TierAttempt {
     tier: string;
     provider: 'free-tier' | 'claude';
     /** 0 = first try at this tier; 1.. = repair rounds (D8). */
     repairRound: number;
+    /** Best-of-k variant index within round 0 (0 = primary, 1.. = diversified). */
+    variant?: number;
+    /** Generator model that produced this candidate (set for cross-model best-of-k). */
+    model?: string;
     ok: boolean;
     passed: boolean;
     latencyMs: number;
@@ -66,6 +84,13 @@ export interface QeExecutionResult {
     escalated: boolean;
     /** True iff a same-tier repair round produced the passing output. */
     repaired: boolean;
+    /** True iff best-of-k (k>1) diversity at a round produced the passing output. */
+    bestOf: boolean;
+    /**
+     * True iff the outcome was withheld from routing-feedback because the gate was
+     * a self-authored oracle (06 §10 Goodhart guard) — it cannot lift confidence.
+     */
+    goodhartGuarded: boolean;
     /** Per-attempt trace, cheapest → most capable. */
     attempts: TierAttempt[];
 }
@@ -79,6 +104,15 @@ export interface FreeTierExecutorOptions {
     env?: NodeJS.ProcessEnv;
     /** Default same-tier repair retries when a request omits `repairAttempts`. */
     defaultRepairAttempts?: number;
+    /**
+     * Cross-model best-of-k (A12, measured +6 composite over single-model). When set
+     * AND the START tier is free-tier, round-0 best-of-k draws each candidate from a
+     * DIFFERENT provider in this pool (e.g. local qwen + an OpenRouter model) instead
+     * of one model's temperature/prompt variants — diverse models cover each other's
+     * failures and raise the union. Selection stays the objective verifier (first-pass).
+     * Omit ⇒ single-model best-of-k (unchanged).
+     */
+    candidateProviders?: FreeTierProviderConfig[];
     /** D9 sink: record each completed task outcome (→ routing-feedback). */
     onOutcome?: (o: {
         agentId: string;
@@ -103,11 +137,19 @@ export declare class FreeTierEscalatingExecutor {
     private readonly baseTier;
     private readonly defaultRepairAttempts;
     private readonly onOutcome?;
+    /** Resolved cross-model generator pool (A12); undefined ⇒ single-model best-of-k. */
+    private readonly candidateProviders?;
     constructor(opts: FreeTierExecutorOptions);
     /** Expose the tracker so a coordinator can inspect/share adaptation state. */
     getTracker(): AutoEscalationTracker<string>;
     /** Run ONE tier once; never throws — failure becomes `{ok:false}` so we repair/escalate. */
     private runTier;
+    /**
+     * Best-of-k diversity turn (06 §12): nudge the model toward a structurally
+     * different valid solution. Deterministic by `variant` index (no RNG) so runs
+     * replay identically.
+     */
+    private diversify;
     /** Build the D8 repair turn: show the model its rejected output + why. */
     private repairMessages;
     /**