agentic-qe 3.11.3 → 3.11.5

package/dist/planning/plan-executor.d.ts

@@ -13,6 +13,15 @@
  */
 import type { GOAPPlan, ExecutionStep, V3WorldState } from './types.js';
 import type { GOAPPlanner } from './goap-planner.js';
+import type { DomainName } from '../shared/types/index.js';
+/**
+ * A14: resolves a real, initialized domain plugin's public API — the same
+ * shape `Kernel.getDomainAPI<T>()` returns and `DefaultProtocolExecutor`
+ * dispatches through. Returns undefined when the domain isn't loaded/no
+ * kernel is available; PlanExecutor must degrade to a clear "not
+ * available" error, never a fabricated result, when this returns undefined.
+ */
+export type GetDomainAPIFn = (domain: DomainName) => unknown | undefined;
 /**
  * Configuration for plan execution
  */
@@ -34,6 +43,16 @@ export interface ExecutionConfig {
      * @default true
      */
     useUnified: boolean;
+    /**
+     * A14: when true, every step is simulated via the injected AgentSpawner
+     * regardless of an action's `implemented` flag — for previews/testing.
+     * When false (default), implemented actions dispatch to a real domain API
+     * method (via the constructor's `getDomainAPI`); actions with no real
+     * binding return a clear "not implemented" failure rather than a
+     * simulated success.
+     * @default false
+     */
+    dryRun: boolean;
 }
 /**
  * Result of executing a complete plan
@@ -118,6 +137,18 @@ export interface AgentSpawner {
  * ```
  */
 export declare class PlanExecutor {
+    /**
+     * A14: resolves real domain plugin APIs, mirroring
+     * DefaultProtocolExecutor's constructor-injected getDomainAPI. When
+     * provided (non-undefined), `implemented: true` actions dispatch to a
+     * real domain method instead of the simulated `spawner` — this is an
+     * opt-in so every EXISTING caller/test that constructs a PlanExecutor
+     * without this param keeps its current (simulated) behavior unchanged.
+     * `implemented: false` actions always fail clearly regardless of this
+     * param — fabricating success for a known-unimplemented action is
+     * exactly the problem this exists to eliminate.
+     */
+    private readonly getDomainAPI?;
     private db;
     private planner;
     private spawner;
@@ -133,13 +164,32 @@ export declare class PlanExecutor {
      * @param dbPath - Path to SQLite database (defaults to in-memory, ignored if useUnified=true)
      * @param config - Execution configuration options
      */
-    constructor(planner: GOAPPlanner, spawner: AgentSpawner, dbPath?: string, config?: Partial<ExecutionConfig>);
+    constructor(planner: GOAPPlanner, spawner: AgentSpawner, dbPath?: string, config?: Partial<ExecutionConfig>, 
+    /**
+     * A14: resolves real domain plugin APIs, mirroring
+     * DefaultProtocolExecutor's constructor-injected getDomainAPI. When
+     * provided (non-undefined), `implemented: true` actions dispatch to a
+     * real domain method instead of the simulated `spawner` — this is an
+     * opt-in so every EXISTING caller/test that constructs a PlanExecutor
+     * without this param keeps its current (simulated) behavior unchanged.
+     * `implemented: false` actions always fail clearly regardless of this
+     * param — fabricating success for a known-unimplemented action is
+     * exactly the problem this exists to eliminate.
+     */
+    getDomainAPI?: GetDomainAPIFn | undefined);
     /**
      * Initialize the executor - creates database tables
      */
     initialize(): Promise<void>;
     /**
-     * Create execution tracking tables
+     * Create execution tracking tables.
+     *
+     * A14: previously invented parallel execution_results/executed_steps
+     * tables with no relationship to the canonical schema. Now uses the same
+     * goap_execution_steps table the unified-storage path relies on (created
+     * via unified-memory-schemas.ts's GOAP_SCHEMA + v11 migration) — this
+     * legacy (non-unified) path just needs to create it directly since it
+     * doesn't go through that migration chain.
      */
     private createTables;
     /**
@@ -164,6 +214,16 @@ export declare class PlanExecutor {
      * Execute a single step
      */
     private executeStep;
+    /**
+     * A14: dispatch an `implemented: true` action to its real domain API
+     * method — mirrors DefaultProtocolExecutor.executeAction()'s resolve →
+     * lookup → invoke pattern, but for GOAPActions instead of ProtocolActions.
+     * Every non-success path returns a clear, specific reason (no domain
+     * loaded, no such method, threw, timed out) rather than a generic
+     * failure — this is what a user should see instead of a fabricated
+     * `successRate: 0.95` roll.
+     */
+    private executeRealAction;
     /**
      * Build a task description for an agent
      */
@@ -186,19 +246,39 @@ export declare class PlanExecutor {
      */
     isExecuting(): boolean;
     /**
-     * Get execution history
+     * Get execution history.
+     *
+     * A14: reconstructed from goap_execution_steps (grouped by execution_id)
+     * instead of read from an invented execution_results table. The
+     * execution-level `status` is derived, not stored directly — steps don't
+     * carry an execution-level concept of 'partial' (a replan-specific
+     * in-memory result of executeWithCallbacks' recursion), so a replanned
+     * execution that ultimately succeeded may read back here as 'completed'
+     * rather than 'partial'. 'cancelled' is inferred from recording fewer
+     * steps than the plan called for; 'failed' takes priority when any step
+     * failed.
      *
      * @param planId - Filter by plan ID (optional)
      * @param limit - Maximum number of results (default: 100)
      * @returns Array of execution results
      */
     getExecutionHistory(planId?: string, limit?: number): Promise<ExecutionResult[]>;
+    /** Number of actions in a saved plan, or null if the plan can't be found/parsed. */
+    private getPlannedActionCount;
     /**
      * Get executed steps for an execution
      */
     private getExecutedSteps;
     /**
-     * Persist execution result to database
+     * Persist execution result to database.
+     *
+     * A14: writes to the canonical goap_execution_steps table (one row per
+     * step per execution attempt, grouped by executionId) instead of an
+     * invented execution_results/executed_steps pair. The execution-level
+     * summary (status/timing) that execution_results used to hold now lives
+     * on goap_plans itself — status/executed_at/completed_at were already
+     * part of that table's schema but never actually written by anything
+     * before this fix.
      */
     private persistExecutionResult;
     /**

package/dist/planning/plan-executor.js

@@ -27,7 +27,23 @@ const DEFAULT_CONFIG = {
     parallelExecution: false,
     recordWorldState: true,
     useUnified: true, // ADR-046: Default to unified storage
+    dryRun: false, // A14: real dispatch is the default going forward
 };
+/**
+ * A14: safely render a real domain method's return value into
+ * ExecutedStep.agentOutput (a string field). Truncates to keep large
+ * results (e.g. a full coverage report) out of the execution log; never
+ * throws on circular references or non-serializable values.
+ */
+function safeStringify(value, maxLength = 2000) {
+    try {
+        const str = typeof value === 'string' ? value : JSON.stringify(value);
+        return str.length > maxLength ? `${str.slice(0, maxLength)}...(truncated)` : str;
+    }
+    catch {
+        return String(value);
+    }
+}
 // ============================================================================
 // Plan Executor Class
 // ============================================================================
@@ -50,6 +66,7 @@ const DEFAULT_CONFIG = {
  * ```
  */
 export class PlanExecutor {
+    getDomainAPI;
     db;
     planner;
     spawner;
@@ -65,7 +82,20 @@ export class PlanExecutor {
      * @param dbPath - Path to SQLite database (defaults to in-memory, ignored if useUnified=true)
      * @param config - Execution configuration options
      */
-    constructor(planner, spawner, dbPath, config) {
+    constructor(planner, spawner, dbPath, config, 
+    /**
+     * A14: resolves real domain plugin APIs, mirroring
+     * DefaultProtocolExecutor's constructor-injected getDomainAPI. When
+     * provided (non-undefined), `implemented: true` actions dispatch to a
+     * real domain method instead of the simulated `spawner` — this is an
+     * opt-in so every EXISTING caller/test that constructs a PlanExecutor
+     * without this param keeps its current (simulated) behavior unchanged.
+     * `implemented: false` actions always fail clearly regardless of this
+     * param — fabricating success for a known-unimplemented action is
+     * exactly the problem this exists to eliminate.
+     */
+    getDomainAPI) {
+        this.getDomainAPI = getDomainAPI;
         this.planner = planner;
         this.spawner = spawner;
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -110,49 +140,39 @@ export class PlanExecutor {
         this.initialized = true;
     }
     /**
-     * Create execution tracking tables
+     * Create execution tracking tables.
+     *
+     * A14: previously invented parallel execution_results/executed_steps
+     * tables with no relationship to the canonical schema. Now uses the same
+     * goap_execution_steps table the unified-storage path relies on (created
+     * via unified-memory-schemas.ts's GOAP_SCHEMA + v11 migration) — this
+     * legacy (non-unified) path just needs to create it directly since it
+     * doesn't go through that migration chain.
      */
     createTables() {
-        // Execution results table
         this.db.exec(`
-      CREATE TABLE IF NOT EXISTS execution_results (
+      CREATE TABLE IF NOT EXISTS goap_execution_steps (
         id TEXT PRIMARY KEY,
         plan_id TEXT NOT NULL,
-        status TEXT NOT NULL,
-        steps_completed INTEGER DEFAULT 0,
-        steps_failed INTEGER DEFAULT 0,
-        total_duration_ms INTEGER DEFAULT 0,
-        final_world_state TEXT,
-        error_message TEXT,
-        created_at TEXT DEFAULT (datetime('now'))
-      )
-    `);
-        // Executed steps table
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS executed_steps (
-        id TEXT PRIMARY KEY,
         execution_id TEXT NOT NULL,
-        plan_id TEXT NOT NULL,
         action_id TEXT NOT NULL,
         step_order INTEGER NOT NULL,
-        status TEXT NOT NULL,
+        world_state_before TEXT,
+        world_state_after TEXT,
+        status TEXT NOT NULL DEFAULT 'pending',
         retries INTEGER DEFAULT 0,
-        started_at TEXT NOT NULL,
-        completed_at TEXT,
+        started_at TEXT,
         duration_ms INTEGER,
         agent_id TEXT,
         agent_output TEXT,
-        world_state_before TEXT,
-        world_state_after TEXT,
         error_message TEXT,
-        FOREIGN KEY (execution_id) REFERENCES execution_results(id)
+        created_at TEXT DEFAULT (datetime('now'))
       )
     `);
-        // Indexes
         this.db.exec(`
-      CREATE INDEX IF NOT EXISTS idx_exec_results_plan ON execution_results(plan_id);
-      CREATE INDEX IF NOT EXISTS idx_exec_steps_execution ON executed_steps(execution_id);
-      CREATE INDEX IF NOT EXISTS idx_exec_steps_action ON executed_steps(action_id);
+      CREATE INDEX IF NOT EXISTS idx_goap_exec_steps_plan ON goap_execution_steps(plan_id);
+      CREATE INDEX IF NOT EXISTS idx_goap_exec_steps_execution ON goap_execution_steps(execution_id);
+      CREATE INDEX IF NOT EXISTS idx_goap_exec_steps_action ON goap_execution_steps(action_id);
     `);
     }
     // ==========================================================================
@@ -316,6 +336,25 @@ export class PlanExecutor {
                 error: `Preconditions not met for action: ${action.name}`,
             };
         }
+        // A14: an action explicitly marked as having no real domain backing
+        // must never report a fabricated success — regardless of dryRun or
+        // whether a kernel is available. This is the actual fix for the "mock
+        // executor fabricates successRate: 0.95 results indistinguishable from
+        // real execution" problem: known-unimplemented actions now fail
+        // honestly instead of rolling dice.
+        if (action.implemented === false) {
+            return {
+                success: false,
+                newState: currentState,
+                error: `Action '${action.name}' has no real implementation yet (not simulated — see GOAPAction.implemented)`,
+            };
+        }
+        // A14: real dispatch — opt-in via constructor-injected getDomainAPI
+        // (mirrors DefaultProtocolExecutor). Existing callers that construct a
+        // PlanExecutor without it keep today's simulated behavior unchanged.
+        if (!this.config.dryRun && this.getDomainAPI && action.implemented === true) {
+            return this.executeRealAction(action, currentState);
+        }
         // Build task description
         const taskDescription = this.buildTaskDescription(action);
         try {
@@ -350,6 +389,76 @@ export class PlanExecutor {
             };
         }
     }
+    /**
+     * A14: dispatch an `implemented: true` action to its real domain API
+     * method — mirrors DefaultProtocolExecutor.executeAction()'s resolve →
+     * lookup → invoke pattern, but for GOAPActions instead of ProtocolActions.
+     * Every non-success path returns a clear, specific reason (no domain
+     * loaded, no such method, threw, timed out) rather than a generic
+     * failure — this is what a user should see instead of a fabricated
+     * `successRate: 0.95` roll.
+     */
+    async executeRealAction(action, currentState) {
+        if (!action.qeDomain) {
+            return {
+                success: false,
+                newState: currentState,
+                error: `Action '${action.name}' has no qeDomain to resolve a real API from`,
+            };
+        }
+        if (!action.method) {
+            return {
+                success: false,
+                newState: currentState,
+                error: `Action '${action.name}' is marked implemented but has no method binding`,
+            };
+        }
+        let api;
+        try {
+            api = this.getDomainAPI(action.qeDomain);
+        }
+        catch (error) {
+            return {
+                success: false,
+                newState: currentState,
+                error: `Failed to resolve domain '${action.qeDomain}': ${toErrorMessage(error)}`,
+            };
+        }
+        if (!api) {
+            return {
+                success: false,
+                newState: currentState,
+                error: `Domain '${action.qeDomain}' is not available (kernel not initialized, or the domain isn't loaded — try fleet_init)`,
+            };
+        }
+        const method = api[action.method];
+        if (typeof method !== 'function') {
+            return {
+                success: false,
+                newState: currentState,
+                error: `Domain '${action.qeDomain}' has no method '${action.method}'`,
+            };
+        }
+        try {
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Step timeout after ${this.config.stepTimeoutMs}ms`)), this.config.stepTimeoutMs));
+            const invokePromise = method.call(api, action.params ?? {});
+            const result = await Promise.race([invokePromise, timeoutPromise]);
+            const newState = this.applyEffects(currentState, action.effects);
+            return {
+                success: true,
+                newState,
+                output: safeStringify(result),
+                agentId: `domain:${action.qeDomain}`,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                newState: currentState,
+                error: toErrorMessage(error),
+            };
+        }
+    }
     /**
      * Build a task description for an agent
      */
@@ -420,7 +529,17 @@ export class PlanExecutor {
     // Execution History
     // ==========================================================================
     /**
-     * Get execution history
+     * Get execution history.
+     *
+     * A14: reconstructed from goap_execution_steps (grouped by execution_id)
+     * instead of read from an invented execution_results table. The
+     * execution-level `status` is derived, not stored directly — steps don't
+     * carry an execution-level concept of 'partial' (a replan-specific
+     * in-memory result of executeWithCallbacks' recursion), so a replanned
+     * execution that ultimately succeeded may read back here as 'completed'
+     * rather than 'partial'. 'cancelled' is inferred from recording fewer
+     * steps than the plan called for; 'failed' takes priority when any step
+     * failed.
      *
      * @param planId - Filter by plan ID (optional)
      * @param limit - Maximum number of results (default: 100)
@@ -428,37 +547,65 @@ export class PlanExecutor {
      */
     async getExecutionHistory(planId, limit = 100) {
         await this.initialize();
-        let query = 'SELECT * FROM execution_results';
+        let query = `
+      SELECT
+        execution_id,
+        plan_id,
+        MIN(created_at) as started_at,
+        SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as steps_completed,
+        SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as steps_failed,
+        SUM(COALESCE(duration_ms, 0)) as total_duration_ms,
+        COUNT(*) as steps_recorded,
+        MAX(CASE WHEN status = 'failed' THEN error_message END) as last_error
+      FROM goap_execution_steps
+    `;
         const params = [];
         if (planId) {
             query += ' WHERE plan_id = ?';
             params.push(planId);
         }
-        query += ' ORDER BY created_at DESC LIMIT ?';
+        query += ' GROUP BY execution_id, plan_id ORDER BY started_at DESC LIMIT ?';
         params.push(limit);
         const rows = this.db.prepare(query).all(...params);
         return Promise.all(rows.map(async (row) => {
-            const steps = await this.getExecutedSteps(row.id);
+            const steps = await this.getExecutedSteps(row.execution_id);
+            const finalWorldState = [...steps].reverse().find((s) => s.worldStateAfter)?.worldStateAfter;
+            const plannedStepCount = this.getPlannedActionCount(row.plan_id);
+            let status;
+            if (row.steps_failed > 0)
+                status = 'failed';
+            else if (plannedStepCount != null && row.steps_recorded < plannedStepCount)
+                status = 'cancelled';
+            else
+                status = 'completed';
             return {
                 planId: row.plan_id,
-                status: row.status,
+                status,
                 stepsCompleted: row.steps_completed,
                 stepsFailed: row.steps_failed,
                 totalDurationMs: row.total_duration_ms,
-                finalWorldState: row.final_world_state
-                    ? safeJsonParse(row.final_world_state)
-                    : undefined,
-                error: row.error_message ?? undefined,
+                finalWorldState,
+                error: row.last_error ?? undefined,
                 steps,
             };
         }));
     }
+    /** Number of actions in a saved plan, or null if the plan can't be found/parsed. */
+    getPlannedActionCount(planId) {
+        const row = this.db
+            .prepare('SELECT action_sequence FROM goap_plans WHERE id = ?')
+            .get(planId);
+        if (!row)
+            return null;
+        const actionIds = safeJsonParse(row.action_sequence);
+        return Array.isArray(actionIds) ? actionIds.length : null;
+    }
     /**
      * Get executed steps for an execution
      */
     async getExecutedSteps(executionId) {
         const rows = this.db
-            .prepare(`SELECT * FROM executed_steps WHERE execution_id = ? ORDER BY step_order`)
+            .prepare(`SELECT * FROM goap_execution_steps WHERE execution_id = ? ORDER BY step_order`)
             .all(executionId);
         return rows.map((row) => ({
             id: row.id,
@@ -480,8 +627,10 @@ export class PlanExecutor {
             agentId: row.agent_id ?? undefined,
             error: row.error_message ?? undefined,
             retries: row.retries,
-            startedAt: new Date(row.started_at),
-            completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
+            startedAt: row.started_at ? new Date(row.started_at) : new Date(row.created_at),
+            completedAt: row.started_at && row.duration_ms != null
+                ? new Date(new Date(row.started_at).getTime() + row.duration_ms)
+                : undefined,
             agentOutput: row.agent_output ?? undefined,
             worldStateBefore: row.world_state_before
                 ? safeJsonParse(row.world_state_before)
@@ -495,28 +644,44 @@ export class PlanExecutor {
     // Persistence
     // ==========================================================================
     /**
-     * Persist execution result to database
+     * Persist execution result to database.
+     *
+     * A14: writes to the canonical goap_execution_steps table (one row per
+     * step per execution attempt, grouped by executionId) instead of an
+     * invented execution_results/executed_steps pair. The execution-level
+     * summary (status/timing) that execution_results used to hold now lives
+     * on goap_plans itself — status/executed_at/completed_at were already
+     * part of that table's schema but never actually written by anything
+     * before this fix.
      */
     async persistExecutionResult(executionId, result) {
-        // Insert execution result
-        this.db
-            .prepare(`
-      INSERT INTO execution_results (
-        id, plan_id, status, steps_completed, steps_failed,
-        total_duration_ms, final_world_state, error_message
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-    `)
-            .run(executionId, result.planId, result.status, result.stepsCompleted, result.stepsFailed, result.totalDurationMs, result.finalWorldState ? JSON.stringify(result.finalWorldState) : null, result.error ?? null);
-        // Insert executed steps
         const insertStep = this.db.prepare(`
-      INSERT INTO executed_steps (
-        id, execution_id, plan_id, action_id, step_order, status,
-        retries, started_at, completed_at, duration_ms, agent_id,
+      INSERT INTO goap_execution_steps (
+        id, plan_id, execution_id, action_id, step_order, status,
+        retries, started_at, duration_ms, agent_id,
         agent_output, world_state_before, world_state_after, error_message
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         for (const step of result.steps) {
-            insertStep.run(step.id, executionId, step.planId, step.action.id, step.stepOrder, step.status, step.retries, step.startedAt.toISOString(), step.completedAt?.toISOString() ?? null, step.durationMs ?? null, step.agentId ?? null, step.agentOutput ?? null, step.worldStateBefore ? JSON.stringify(step.worldStateBefore) : null, step.worldStateAfter ? JSON.stringify(step.worldStateAfter) : null, step.error ?? null);
+            insertStep.run(step.id, step.planId, executionId, step.action.id, step.stepOrder, step.status, step.retries, step.startedAt.toISOString(), step.durationMs ?? null, step.agentId ?? null, step.agentOutput ?? null, step.worldStateBefore ? JSON.stringify(step.worldStateBefore) : null, step.worldStateAfter ? JSON.stringify(step.worldStateAfter) : null, step.error ?? null);
+        }
+        // Reflects only the most recent execution attempt for this plan — a
+        // deliberate, documented scope limit: goap_plans is one row per plan,
+        // not per attempt. Full per-attempt history remains queryable via
+        // goap_execution_steps grouped by execution_id (see getExecutionHistory).
+        try {
+            this.db.prepare(`
+        UPDATE goap_plans SET status = ?, executed_at = COALESCE(executed_at, ?), completed_at = ?
+        WHERE id = ?
+      `).run(result.status === 'completed' ? 'completed'
+                : result.status === 'cancelled' ? 'cancelled'
+                    : 'failed', new Date(Date.now() - result.totalDurationMs).toISOString(), new Date().toISOString(), result.planId);
+        }
+        catch (error) {
+            // Best-effort — a plan row might not exist yet in edge cases (e.g.
+            // executing a plan object that was never saved). Must not fail the
+            // execution result the caller is waiting on.
+            console.warn('[PlanExecutor] Failed to update goap_plans status (non-fatal):', error);
         }
     }
     /**

package/dist/planning/types.d.ts

@@ -123,6 +123,27 @@ export interface GOAPAction {
     category: 'test' | 'security' | 'performance' | 'analysis' | 'coverage' | 'fleet' | 'quality';
     /** QE domain this action belongs to */
     qeDomain?: QEDomain;
+    /**
+     * A14: real domain API method to invoke when this action is executed —
+     * `kernel.getDomainAPI(qeDomain)[method](params)`, mirroring how
+     * DefaultProtocolExecutor dispatches ProtocolActions. Undefined when
+     * `implemented` is not true.
+     */
+    method?: string;
+    /**
+     * Static params template passed to `method`. GOAP actions are abstract
+     * plan steps (not bound to concrete files/targets at definition time),
+     * so this is often `{}` — many real domain methods need runtime context
+     * a plan step doesn't carry, and will legitimately error on missing
+     * required params rather than being fabricated a plausible-looking value.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * True only when `method` names a real, non-stub domain API method.
+     * Actions without a real implementation MUST report "not implemented"
+     * when executed, not a fabricated success/failure — see GOAPExecutor.
+     */
+    implemented?: boolean;
 }
 /**
  * GOAP Goal - Target state to achieve through planning
@@ -240,6 +261,12 @@ export interface GOAPActionRecord {
     qe_domain: string | null;
     created_at: string;
     updated_at: string;
+    /** A14: real domain API method binding, null when not implemented */
+    method: string | null;
+    /** A14: JSON params template */
+    params: string | null;
+    /** A14: 1 when `method` is a real (non-stub) domain API binding, else 0 */
+    implemented: number;
 }
 /**
  * Database record for goap_plans table

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

@@ -14,9 +14,12 @@
 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";
+/** Default cheap tier. qwen3-coder:30b — same 30B MoE class/RAM as qwen3:30b-a3b
+ *  and IDENTICAL measured quality (2026-06-29 oracle bench, 8 fixtures: both 6/8,
+ *  75% avg mutation kill), but ~14× faster wall-clock (the code-tuned model does
+ *  not spend ~70s "thinking" before answering). qwen3:8b stays off-default: D3
+ *  measured it well below this (3/8). */
+export declare const DEFAULT_FREE_TIER_MODEL = "qwen3-coder:30b";
 /** 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`. */

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

@@ -14,9 +14,12 @@
 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';
+/** Default cheap tier. qwen3-coder:30b — same 30B MoE class/RAM as qwen3:30b-a3b
+ *  and IDENTICAL measured quality (2026-06-29 oracle bench, 8 fixtures: both 6/8,
+ *  75% avg mutation kill), but ~14× faster wall-clock (the code-tuned model does
+ *  not spend ~70s "thinking" before answering). qwen3:8b stays off-default: D3
+ *  measured it well below this (3/8). */
+export const DEFAULT_FREE_TIER_MODEL = 'qwen3-coder:30b';
 /**
  * Build a cheap-first escalating executor from coordinator config + (optional)
  * router. Returns `null` when the free tier is not opted in — callers store the

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

@@ -15,6 +15,7 @@
  * never leaves the start tier (the "no escalation yet" mode).
  */
 import { type ChatMessage } from './provider.js';
+import { TestGenPatternCache } from './pattern-cache.js';
 import { AutoEscalationTracker } from '../escalation/auto-escalation-tracker.js';
 import type { QeRoutingLadder, FreeTierProviderConfig } from './types.js';
 import type { AgentTier } from '../routing-config.js';
@@ -57,6 +58,12 @@ export interface QeTaskRequest {
      * `objective` (existing callers inject real oracles, e.g. a coverage/test run).
      */
     oracleKind?: 'objective' | 'self-authored';
+    /**
+     * #6: the code under test, for the pattern cache. When set AND the executor
+     * has a `patternCache`, a cache hit (re-verified by `verify`) short-circuits
+     * generation entirely. Omit to disable caching for this task.
+     */
+    cacheText?: string;
 }
 export interface TierAttempt {
     tier: string;
@@ -113,6 +120,11 @@ export interface FreeTierExecutorOptions {
      * Omit ⇒ single-model best-of-k (unchanged).
      */
     candidateProviders?: FreeTierProviderConfig[];
+    /**
+     * #6: ruvLLM-style pattern cache. When provided and a request carries
+     * `cacheText`, a verified cache hit skips all LLM tiers. Omit to disable.
+     */
+    patternCache?: TestGenPatternCache;
     /** D9 sink: record each completed task outcome (→ routing-feedback). */
     onOutcome?: (o: {
         agentId: string;
@@ -139,6 +151,8 @@ export declare class FreeTierEscalatingExecutor {
     private readonly onOutcome?;
     /** Resolved cross-model generator pool (A12); undefined ⇒ single-model best-of-k. */
     private readonly candidateProviders?;
+    /** #6: optional pattern cache; undefined ⇒ caching disabled. */
+    private readonly patternCache?;
     constructor(opts: FreeTierExecutorOptions);
     /** Expose the tracker so a coordinator can inspect/share adaptation state. */
     getTracker(): AutoEscalationTracker<string>;