agentic-qe 3.12.3 → 3.13.1

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

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

package/dist/mcp/types.d.ts

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

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

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

package/dist/optimization/session-cache.js

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

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

@@ -0,0 +1,55 @@
+/**
+ * Auto-restore for the unified `memory.db` (M3.2, inspired by ruflo v3.25.2's
+ * backup-auto-restore, adapted to better-sqlite3).
+ *
+ * Hardened after a qe-court review (ADR-124) surfaced three data-loss risks in
+ * the first cut:
+ *   F3 — `isDbHealthy` via a readonly open + integrity_check FALSE-NEGATIVES a
+ *        HEALTHY WAL db when `-shm` is zeroed/inaccessible over virtiofs (the
+ *        exact documented failure mode), which would have parked a good DB and
+ *        reverted to an older backup. FIX: the live-corruption signal is now the
+ *        SQLite HEADER — a `-wal`/`-shm` problem does not corrupt the main file,
+ *        so we only treat a missing/garbage header (zeroed/not-a-db) as corrupt.
+ *   F2 — non-atomic `copyFileSync` + no lock let concurrent hook processes tear
+ *        the restored image. FIX: copy to a temp in the same dir → atomic rename,
+ *        under a best-effort exclusive lock so only one process restores.
+ *   backup trust — a backup we are about to promote to the LIVE db still gets a
+ *        FULL `integrity_check` (it is a static file, safe to open readonly).
+ *
+ * DATA-PROTECTION INVARIANTS (this file must never make things worse):
+ *   - The corrupt original is RENAMED to `<db>.corrupt-<ts>`, NEVER deleted.
+ *   - A header-valid main file is treated as HEALTHY — we never park a DB that
+ *     might just have a transient `-wal`/`-shm` issue (a writable open rebuilds
+ *     `-shm`). We prefer "manual restore" over "auto-destroy a healthy DB".
+ *   - A backup is used only if it passes `PRAGMA integrity_check`.
+ *   - If no verified backup exists, we do NOTHING (leave the DB for inspection).
+ */
+/**
+ * True if the main DB file is structurally a database (or absent/empty = a fresh
+ * DB the caller will create). LIVE-corruption signal only: it deliberately does
+ * NOT open the DB or run integrity_check, because a `-wal`/`-shm` fault over
+ * virtiofs makes a HEALTHY db unreadable and we must not mistake that for
+ * corruption (F3). Only a missing/garbage header — the zeroed/not-a-db case —
+ * is "corrupt". A header-valid-but-page-corrupt file is left for MANUAL restore
+ * rather than risk auto-parking a healthy DB.
+ */
+export declare function isDbHealthy(dbPath: string): boolean;
+export interface RestoreResult {
+    restored: boolean;
+    reason: 'healthy' | 'no-verified-backup' | 'restored-from-backup' | 'restore-in-progress' | 'park-failed' | 'copy-failed';
+    backupUsed?: string;
+    parkedTo?: string;
+}
+/** Default verified-backup directory (matches `scripts/aqe-db-backup.sh`). */
+export declare function defaultBackupDir(dbPath: string): string;
+/**
+ * If `dbPath`'s main file is unambiguously corrupt (bad SQLite header), park it
+ * and atomically restore the newest verified backup. No-op (and non-destructive)
+ * when the DB is healthy, when no good backup exists, or when another process is
+ * already restoring.
+ */
+export declare function attemptAutoRestore(dbPath: string, opts?: {
+    backupDir?: string;
+    now?: number;
+}): RestoreResult;
+//# sourceMappingURL=db-recovery.d.ts.map

package/dist/shared/db-recovery.js

@@ -0,0 +1,184 @@
+/**
+ * Auto-restore for the unified `memory.db` (M3.2, inspired by ruflo v3.25.2's
+ * backup-auto-restore, adapted to better-sqlite3).
+ *
+ * Hardened after a qe-court review (ADR-124) surfaced three data-loss risks in
+ * the first cut:
+ *   F3 — `isDbHealthy` via a readonly open + integrity_check FALSE-NEGATIVES a
+ *        HEALTHY WAL db when `-shm` is zeroed/inaccessible over virtiofs (the
+ *        exact documented failure mode), which would have parked a good DB and
+ *        reverted to an older backup. FIX: the live-corruption signal is now the
+ *        SQLite HEADER — a `-wal`/`-shm` problem does not corrupt the main file,
+ *        so we only treat a missing/garbage header (zeroed/not-a-db) as corrupt.
+ *   F2 — non-atomic `copyFileSync` + no lock let concurrent hook processes tear
+ *        the restored image. FIX: copy to a temp in the same dir → atomic rename,
+ *        under a best-effort exclusive lock so only one process restores.
+ *   backup trust — a backup we are about to promote to the LIVE db still gets a
+ *        FULL `integrity_check` (it is a static file, safe to open readonly).
+ *
+ * DATA-PROTECTION INVARIANTS (this file must never make things worse):
+ *   - The corrupt original is RENAMED to `<db>.corrupt-<ts>`, NEVER deleted.
+ *   - A header-valid main file is treated as HEALTHY — we never park a DB that
+ *     might just have a transient `-wal`/`-shm` issue (a writable open rebuilds
+ *     `-shm`). We prefer "manual restore" over "auto-destroy a healthy DB".
+ *   - A backup is used only if it passes `PRAGMA integrity_check`.
+ *   - If no verified backup exists, we do NOTHING (leave the DB for inspection).
+ */
+import { existsSync, renameSync, copyFileSync, readdirSync, statSync, openSync, readSync, closeSync, writeFileSync, rmSync, } from 'node:fs';
+import { join, dirname } from 'node:path';
+import Database from 'better-sqlite3';
+/** The 16-byte magic every valid SQLite database file starts with. */
+const SQLITE_MAGIC = Buffer.concat([Buffer.from('SQLite format 3', 'latin1'), Buffer.from([0])]);
+/**
+ * True if the main DB file is structurally a database (or absent/empty = a fresh
+ * DB the caller will create). LIVE-corruption signal only: it deliberately does
+ * NOT open the DB or run integrity_check, because a `-wal`/`-shm` fault over
+ * virtiofs makes a HEALTHY db unreadable and we must not mistake that for
+ * corruption (F3). Only a missing/garbage header — the zeroed/not-a-db case —
+ * is "corrupt". A header-valid-but-page-corrupt file is left for MANUAL restore
+ * rather than risk auto-parking a healthy DB.
+ */
+export function isDbHealthy(dbPath) {
+    if (!existsSync(dbPath))
+        return true;
+    let size;
+    try {
+        size = statSync(dbPath).size;
+    }
+    catch {
+        return false;
+    }
+    if (size === 0)
+        return true; // freshly-created, not yet written — not corrupt
+    if (size < SQLITE_MAGIC.length)
+        return false; // too small to be a real db
+    let fd;
+    try {
+        fd = openSync(dbPath, 'r');
+        const header = Buffer.alloc(SQLITE_MAGIC.length);
+        readSync(fd, header, 0, SQLITE_MAGIC.length, 0);
+        return header.equals(SQLITE_MAGIC);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/** Full integrity check for a backup we are about to promote to the live DB. */
+function backupIsRestorable(path) {
+    let db;
+    try {
+        db = new Database(path, { readonly: true, fileMustExist: true });
+        return db.pragma('integrity_check', { simple: true }) === 'ok';
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/** Default verified-backup directory (matches `scripts/aqe-db-backup.sh`). */
+export function defaultBackupDir(dbPath) {
+    return join(dirname(dbPath), 'backups', 'verified');
+}
+/** Newest `memory-*.db` in the backup dir that passes a full integrity_check, or null. */
+function newestVerifiedBackup(backupDir) {
+    if (!existsSync(backupDir))
+        return null;
+    const candidates = readdirSync(backupDir)
+        .filter((f) => f.startsWith('memory-') && f.endsWith('.db'))
+        .map((f) => {
+        const path = join(backupDir, f);
+        return { path, mtime: statSync(path).mtimeMs };
+    })
+        .sort((a, b) => b.mtime - a.mtime);
+    for (const c of candidates) {
+        if (backupIsRestorable(c.path))
+            return c.path;
+    }
+    return null;
+}
+/**
+ * If `dbPath`'s main file is unambiguously corrupt (bad SQLite header), park it
+ * and atomically restore the newest verified backup. No-op (and non-destructive)
+ * when the DB is healthy, when no good backup exists, or when another process is
+ * already restoring.
+ */
+export function attemptAutoRestore(dbPath, opts) {
+    if (isDbHealthy(dbPath))
+        return { restored: false, reason: 'healthy' };
+    const backupDir = opts?.backupDir ?? defaultBackupDir(dbPath);
+    const good = newestVerifiedBackup(backupDir);
+    if (!good)
+        return { restored: false, reason: 'no-verified-backup' };
+    // F2: best-effort exclusive lock so concurrent processes don't both restore.
+    const lockPath = `${dbPath}.restore.lock`;
+    try {
+        writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+    }
+    catch {
+        return { restored: false, reason: 'restore-in-progress' };
+    }
+    try {
+        // Re-check under the lock: a peer may have just restored a healthy DB.
+        if (isDbHealthy(dbPath))
+            return { restored: false, reason: 'healthy' };
+        const ts = opts?.now ?? Date.now();
+        const parked = `${dbPath}.corrupt-${ts}`;
+        // Park the corrupt original + any stale WAL/shm. NEVER delete.
+        try {
+            if (existsSync(dbPath))
+                renameSync(dbPath, parked);
+            for (const suffix of ['-wal', '-shm']) {
+                if (existsSync(dbPath + suffix))
+                    renameSync(dbPath + suffix, parked + suffix);
+            }
+        }
+        catch {
+            return { restored: false, reason: 'park-failed' };
+        }
+        // F2: restore atomically — copy to a temp on the same filesystem, then rename.
+        const tmp = `${dbPath}.restoring-${ts}`;
+        try {
+            copyFileSync(good, tmp);
+            renameSync(tmp, dbPath); // atomic on the same fs
+        }
+        catch {
+            try {
+                if (existsSync(tmp))
+                    rmSync(tmp, { force: true });
+                if (!existsSync(dbPath) && existsSync(parked))
+                    renameSync(parked, dbPath);
+            }
+            catch {
+                /* leave parked copy for manual recovery */
+            }
+            return { restored: false, reason: 'copy-failed' };
+        }
+        return { restored: true, reason: 'restored-from-backup', backupUsed: good, parkedTo: parked };
+    }
+    finally {
+        try {
+            rmSync(lockPath, { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+//# sourceMappingURL=db-recovery.js.map

package/dist/shared/llm/billing-modes.js

@@ -10,6 +10,7 @@
 const BILLING_MODE_BY_TYPE = {
     claude: 'metered-api',
     'claude-code': 'subscription',
+    codex: 'subscription',
     openai: 'metered-api',
     openrouter: 'metered-api',
     gemini: 'metered-api',
@@ -45,10 +46,12 @@ export function billingNotice(provider, mode) {
         case 'metered-capped':
             return (`ℹ️  LLM provider "${provider}" bills per-token but enforces a server-side ` +
                 `hard spend cap; it will pause at the cap rather than overspend.`);
-        case 'subscription':
-            return (`ℹ️  LLM provider "${provider}" runs on your Claude Code subscription ` +
+        case 'subscription': {
+            const sub = provider === 'codex' ? 'ChatGPT' : 'Claude Code';
+            return (`ℹ️  LLM provider "${provider}" runs on your ${sub} subscription ` +
                 `(shared plan usage). Worst case is hitting your plan's rate limit and pausing — ` +
                 `no per-token API charges.`);
+        }
         case 'local':
             return undefined;
     }

package/dist/shared/llm/cost-tracker.js

@@ -177,6 +177,7 @@ export class CostTracker {
         const byProvider = {
             claude: 0,
             'claude-code': 0,
+            codex: 0,
             openai: 0,
             ollama: 0,
             openrouter: 0,

package/dist/shared/llm/interfaces.d.ts

@@ -11,7 +11,7 @@
 /**
  * Supported LLM provider types
  */
-export type LLMProviderType = 'claude' | 'claude-code' | 'openai' | 'ollama' | 'openrouter' | 'bedrock' | 'azure-openai' | 'gemini' | 'cognitum';
+export type LLMProviderType = 'claude' | 'claude-code' | 'codex' | 'openai' | 'ollama' | 'openrouter' | 'bedrock' | 'azure-openai' | 'gemini' | 'cognitum';
 /**
  * Message role in a conversation
  */
@@ -273,6 +273,18 @@ export interface ClaudeCodeConfig extends LLMConfig {
     /** Tools to disallow in the headless session (safety). */
     disallowedTools?: string[];
 }
+/**
+ * Codex CLI (subscription) provider configuration (ADR-123 / ADR-124 M3.5).
+ * Runs on the user's ChatGPT subscription by shelling out to `codex exec`,
+ * mirroring the claude-code provider. Gives AQE a cross-vendor (GPT-family)
+ * engine for provider fallback and qe-court prosecutor/juror diversity.
+ */
+export interface CodexConfig extends LLMConfig {
+    /** Path to the `codex` binary (default: 'codex' on PATH). */
+    binaryPath?: string;
+    /** Max concurrent `codex exec` subprocesses. */
+    maxConcurrency?: number;
+}
 /**
  * Cognitum provider configuration (ADR-123). OpenAI-compatible gateway with
  * per-request cost receipts and a server-side hard spend cap.
@@ -294,6 +306,7 @@ export interface ProviderManagerConfig {
     providers: {
         claude?: ClaudeConfig;
         'claude-code'?: ClaudeCodeConfig;
+        codex?: CodexConfig;
         openai?: OpenAIConfig;
         ollama?: OllamaConfig;
         openrouter?: OpenRouterConfig;