agentic-qe 3.12.3 → 3.13.0

package/dist/shared/llm/providers/codex.js

@@ -0,0 +1,305 @@
+/**
+ * Agentic QE v3 — Codex CLI (subscription) Provider (ADR-123 / ADR-124 M3.5)
+ *
+ * Runs QE analysis on the user's ChatGPT subscription by shelling out to the
+ * Codex CLI (`codex exec`) instead of calling the OpenAI API with a paid key.
+ * The CLI authenticates with the user's existing ChatGPT login (~/.codex/auth.json)
+ * and draws from the subscription allowance, so the worst case is "hit the plan
+ * limit and pause" rather than a per-token bill. Mirrors the claude-code provider.
+ *
+ * WHY: gives AQE a cross-vendor (GPT-family) engine — used as a provider fallback
+ * and, crucially, as an independent prosecutor/juror in qe-court (ADR-124), where
+ * a non-Claude, non-Cognitum brain is the strongest form of writer≠juror.
+ *
+ * LOAD-BEARING: the child process env has OPENAI_API_KEY / CODEX_API_KEY stripped.
+ * If present, the CLI could revert to API-key billing and this provider would be
+ * a lie. `parity` test coverage asserts the strip.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createLLMError, } from '../interfaces';
+import { TokenMetricsCollector } from '../../../learning/token-tracker.js';
+/** Env vars whose presence could flip the CLI from subscription to API billing. */
+export const API_BILLING_ENV_VARS = ['OPENAI_API_KEY', 'CODEX_API_KEY'];
+/** Sentinel meaning "let Codex use its own configured default model". */
+export const CODEX_DEFAULT_MODEL = 'default';
+export const DEFAULT_CODEX_CONFIG = {
+    model: CODEX_DEFAULT_MODEL,
+    maxTokens: 4096,
+    temperature: 0.7,
+    timeoutMs: 180000,
+    maxRetries: 1,
+    binaryPath: 'codex',
+    maxConcurrency: 2,
+};
+export class CodexProvider {
+    type = 'codex';
+    name = 'Codex CLI (subscription)';
+    billingMode = 'subscription';
+    config;
+    requestId = 0;
+    availabilityCache;
+    active = 0;
+    queue = [];
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CODEX_CONFIG, ...config };
+        const envConc = Number.parseInt(process.env.AQE_CODEX_CONCURRENCY ?? '', 10);
+        if (Number.isFinite(envConc) && envConc > 0) {
+            this.config.maxConcurrency = envConc;
+        }
+    }
+    async isAvailable() {
+        const now = Date.now();
+        if (this.availabilityCache && now - this.availabilityCache.at < 60_000) {
+            return this.availabilityCache.available;
+        }
+        let available = false;
+        try {
+            const { code } = await this.runProcess(['--version'], undefined, undefined, 5000);
+            available = code === 0;
+        }
+        catch {
+            available = false;
+        }
+        this.availabilityCache = { at: now, available };
+        return available;
+    }
+    async healthCheck() {
+        const start = Date.now();
+        const available = await this.isAvailable();
+        const latencyMs = Date.now() - start;
+        if (!available) {
+            return {
+                healthy: false,
+                latencyMs,
+                error: `Codex CLI ("${this.config.binaryPath}") not found or not runnable. ` +
+                    `Install Codex and log in with your ChatGPT account (\`codex login\`).`,
+            };
+        }
+        return {
+            healthy: true,
+            latencyMs,
+            models: this.getSupportedModels(),
+            details: { binaryPath: this.config.binaryPath, billing: 'subscription' },
+        };
+    }
+    async generate(input, options) {
+        const model = options?.model ?? this.config.model ?? CODEX_DEFAULT_MODEL;
+        const requestId = `codex-${++this.requestId}-${Date.now()}`;
+        const { prompt } = this.flatten(input, options?.systemPrompt);
+        // `codex exec` is agentic; keep it read-only and non-interactive. We capture
+        // just the final assistant message via -o <file> to avoid parsing the noisy
+        // JSONL event stream.
+        const tmp = mkdtempSync(join(tmpdir(), 'aqe-codex-'));
+        const outFile = join(tmp, 'last-message.txt');
+        const args = [
+            'exec',
+            '--skip-git-repo-check',
+            '--sandbox', 'read-only',
+            '-o', outFile,
+        ];
+        if (model && model !== CODEX_DEFAULT_MODEL) {
+            args.push('-m', model);
+        }
+        const start = Date.now();
+        const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs ?? 180000;
+        try {
+            const { code, stderr } = await this.withConcurrency(() => this.runProcess(args, prompt, undefined, timeoutMs));
+            const latencyMs = Date.now() - start;
+            let content = '';
+            try {
+                content = readFileSync(outFile, 'utf8').trim();
+            }
+            catch {
+                content = '';
+            }
+            if (code !== 0 && !content) {
+                throw this.classifyError(stderr || `codex exited with code ${code}`, model);
+            }
+            // Subscription: no per-token receipt. Estimate usage from text length for
+            // visibility only (≈4 chars/token); marginal monetary cost is $0.
+            const promptTokens = Math.ceil(prompt.length / 4);
+            const completionTokens = Math.ceil(content.length / 4);
+            const usage = {
+                promptTokens,
+                completionTokens,
+                totalTokens: promptTokens + completionTokens,
+                cacheCreationTokens: 0,
+                cacheReadTokens: 0,
+            };
+            TokenMetricsCollector.recordTokenUsage(requestId, 'codex-provider', 'llm', 'generate', {
+                inputTokens: usage.promptTokens,
+                outputTokens: usage.completionTokens,
+                totalTokens: usage.totalTokens,
+                estimatedCostUsd: 0,
+            });
+            return {
+                content,
+                model: model === CODEX_DEFAULT_MODEL ? 'codex-default' : model,
+                provider: 'codex',
+                usage,
+                // Subscription billing: marginal cost is $0 and we know it authoritatively.
+                cost: { inputCost: 0, outputCost: 0, totalCost: 0, currency: 'USD', source: 'provider-receipt' },
+                latencyMs,
+                finishReason: 'stop',
+                cached: false,
+                requestId,
+            };
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    async embed(_text, _options) {
+        throw createLLMError('Codex provider does not support embeddings. Use openai, ollama, or cognitum.', 'MODEL_NOT_FOUND', { provider: 'codex', retryable: false });
+    }
+    async complete(prompt, options) {
+        const response = await this.generate(prompt, {
+            model: options?.model,
+            temperature: options?.temperature ?? 0.2,
+            maxTokens: options?.maxTokens ?? 256,
+        });
+        return {
+            completion: response.content,
+            model: response.model,
+            provider: 'codex',
+            usage: response.usage,
+            latencyMs: response.latencyMs,
+            cached: response.cached,
+        };
+    }
+    getConfig() {
+        return { ...this.config };
+    }
+    getSupportedModels() {
+        // Codex resolves the concrete model from its profile/login; these are the
+        // common ids accepted via -m. `default` = whatever the CLI is configured to.
+        return [CODEX_DEFAULT_MODEL, 'gpt-5-codex', 'o3', 'o4-mini'];
+    }
+    getCostPerToken() {
+        return { input: 0, output: 0 };
+    }
+    async dispose() {
+        // No persistent resources.
+    }
+    // -- internals -------------------------------------------------------------
+    flatten(input, systemPromptOpt) {
+        if (typeof input === 'string') {
+            return { prompt: systemPromptOpt ? `${systemPromptOpt}\n\n${input}` : input };
+        }
+        const systemParts = input.filter((m) => m.role === 'system').map((m) => m.content);
+        if (systemPromptOpt)
+            systemParts.unshift(systemPromptOpt);
+        const convo = input
+            .filter((m) => m.role !== 'system')
+            .map((m) => `${m.role === 'assistant' ? 'Assistant' : 'User'}: ${m.content}`)
+            .join('\n\n');
+        const preamble = systemParts.length > 0 ? `${systemParts.join('\n\n')}\n\n` : '';
+        return { prompt: `${preamble}${convo}` };
+    }
+    classifyError(message, model) {
+        const lower = message.toLowerCase();
+        if (lower.includes('rate limit') ||
+            lower.includes('usage limit') ||
+            lower.includes('429') ||
+            lower.includes('quota')) {
+            return createLLMError(message, 'RATE_LIMITED', {
+                provider: 'codex',
+                model,
+                retryable: true,
+                retryAfterMs: 60_000,
+            });
+        }
+        return createLLMError(message, 'PROVIDER_UNAVAILABLE', {
+            provider: 'codex',
+            model,
+            retryable: true,
+        });
+    }
+    /**
+     * Build the child env with API-billing keys stripped (LOAD-BEARING).
+     * Exported logic tested by parity/env-strip tests.
+     */
+    static childEnv(base = process.env) {
+        const env = { ...base };
+        for (const key of API_BILLING_ENV_VARS) {
+            delete env[key];
+        }
+        return env;
+    }
+    runProcess(args, stdin, _unused, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.config.binaryPath ?? 'codex', args, {
+                env: CodexProvider.childEnv(),
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.kill('SIGKILL');
+                reject(createLLMError('codex exec timed out', 'TIMEOUT', {
+                    provider: 'codex',
+                    retryable: true,
+                }));
+            }, timeoutMs);
+            child.stdout.on('data', (d) => (stdout += d.toString()));
+            child.stderr.on('data', (d) => (stderr += d.toString()));
+            child.on('error', (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(createLLMError(`Failed to spawn codex: ${err.message}`, 'PROVIDER_UNAVAILABLE', {
+                    provider: 'codex',
+                    retryable: false,
+                    cause: err,
+                }));
+            });
+            child.on('close', (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve({ code: code ?? 0, stdout, stderr });
+            });
+            // EPIPE guard: if codex exits before reading stdin (e.g. not logged in),
+            // the write/end can emit 'error' on the stdin stream. Without a listener
+            // Node throws an uncaught exception that crashes the calling process. The
+            // 'close'/'error' handlers above already capture the real outcome.
+            child.stdin.on('error', () => { });
+            try {
+                if (stdin !== undefined) {
+                    child.stdin.write(stdin);
+                }
+                child.stdin.end();
+            }
+            catch {
+                /* stream already torn down — the process handlers report the failure */
+            }
+        });
+    }
+    /** Simple semaphore so we don't spawn unbounded `codex` subprocesses. */
+    async withConcurrency(fn) {
+        const limit = this.config.maxConcurrency ?? 2;
+        if (this.active >= limit) {
+            await new Promise((resolve) => this.queue.push(resolve));
+        }
+        this.active++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.active--;
+            const next = this.queue.shift();
+            if (next)
+                next();
+        }
+    }
+}
+//# sourceMappingURL=codex.js.map

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

@@ -4,6 +4,7 @@
  */
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG } from './claude';
 export { ClaudeCodeProvider, DEFAULT_CLAUDE_CODE_CONFIG, API_BILLING_ENV_VARS, type ClaudeCodeConfig, } from './claude-code';
+export { CodexProvider, DEFAULT_CODEX_CONFIG, CODEX_DEFAULT_MODEL, type CodexConfig, } from './codex';
 export { CognitumProvider, DEFAULT_COGNITUM_CONFIG, type CognitumConfig, type CognitumBudget, } from './cognitum';
 export { OpenAIProvider, DEFAULT_OPENAI_CONFIG } from './openai';
 export { OllamaProvider, DEFAULT_OLLAMA_CONFIG } from './ollama';

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

@@ -4,6 +4,7 @@
  */
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG } from './claude';
 export { ClaudeCodeProvider, DEFAULT_CLAUDE_CODE_CONFIG, API_BILLING_ENV_VARS, } from './claude-code';
+export { CodexProvider, DEFAULT_CODEX_CONFIG, CODEX_DEFAULT_MODEL, } from './codex';
 export { CognitumProvider, DEFAULT_COGNITUM_CONFIG, } from './cognitum';
 export { OpenAIProvider, DEFAULT_OPENAI_CONFIG } from './openai';
 export { OllamaProvider, DEFAULT_OLLAMA_CONFIG } from './ollama';

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

@@ -39,6 +39,10 @@ const PROVIDER_ENV_KEYS = {
     // availability is gated on the `claude` binary being on PATH (see the
     // provider's isAvailable()).
     'claude-code': [],
+    // ADR-124 M3.5: codex authenticates via the user's ChatGPT login
+    // (subscription), NOT an env key. Availability is gated on the `codex`
+    // binary being on PATH (see the provider's isAvailable()).
+    codex: [],
     openai: ['OPENAI_API_KEY'],
     ollama: [], // ollama is local; no key required
     openrouter: ['OPENROUTER_API_KEY'],
@@ -59,6 +63,7 @@ const PROVIDER_ENV_KEYS = {
 const RUNTIME_CONSTRUCTIBLE_PROVIDERS = new Set([
     'claude',
     'claude-code',
+    'codex',
     'openai',
     'ollama',
     'openrouter',

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

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

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

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

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

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

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

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

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

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

package/dist/shared/safe-db.js

@@ -9,6 +9,7 @@
  * WAL or busy_timeout. When multiple hook processes ran concurrently, the DB corrupted.
  */
 import Database from 'better-sqlite3';
+import { attemptAutoRestore } from './db-recovery.js';
 /**
  * Open a SQLite database with safe defaults that prevent corruption.
  *
@@ -23,6 +24,22 @@ export function openDatabase(dbPath, opts) {
     const fileMustExist = opts?.fileMustExist ?? false;
     const busyTimeout = opts?.busyTimeout ?? 5000;
     const walMode = opts?.walMode ?? !readonly;
+    // M3.2: recover a malformed DB from a verified backup BEFORE opening it, so a
+    // corrupt memory.db self-heals instead of surfacing errors on first query.
+    // Non-destructive + no-op unless enabled and actually needed.
+    if (opts?.autoRestore && !readonly) {
+        const result = attemptAutoRestore(dbPath, { backupDir: opts.backupDir });
+        if (result.restored) {
+            console.warn(`[safe-db] memory DB at ${dbPath} was malformed; auto-restored from ` +
+                `${result.backupUsed}. Corrupt original parked at ${result.parkedTo}.`);
+        }
+        else if (result.reason === 'no-verified-backup') {
+            // Reached only when the DB is malformed (attemptAutoRestore short-circuits
+            // 'healthy' first) — corrupt AND no backup to restore from.
+            console.error(`[safe-db] memory DB at ${dbPath} appears malformed and NO verified backup ` +
+                `was found to restore from. Leaving it in place for manual inspection.`);
+        }
+    }
     // Environment override for filesystems where WAL is UNSAFE. WAL prevents
     // concurrent-writer corruption on a normal filesystem, but on a macOS
     // Docker/virtiofs bind mount the `-shm` mmap coherence across the

package/dist/skills/qe-court/referee.d.ts

@@ -0,0 +1,62 @@
+/**
+ * QE-Court referee (ADR-124) — the falsifiable core of the adversarial court,
+ * as pure, deterministic functions so the court's invariants are ENFORCED in
+ * code (and unit-testable as oracles), not merely described in the skill doc.
+ *
+ * These back the qe-court acceptance eval (`.claude/skills/qe-court/evals`):
+ *   - verdict resolution + the overturn mechanic (SHIP must survive escalation)
+ *   - panel validation (writer≠juror, vendor diversity)
+ *   - DoE-gated scoring (no un-validated numeric score)
+ *
+ * No I/O, no LLM calls — the orchestration (spawning prosecutors, calling the
+ * two-gate judge) lives in the skill; the RULES live here.
+ */
+export type Verdict = 'SHIP' | 'REMAND' | 'BLOCK';
+/** Coarse model vendor — diversity is measured across vendors, not tiers. */
+export type Vendor = 'claude' | 'cognitum' | 'gpt' | 'openrouter' | 'local' | 'unknown';
+/** A charge filed by a prosecutor (or surfaced by a deeper reviewer). */
+export interface Charge {
+    id: string;
+    /** A fatal charge blocks the ship; a non-fatal charge remands it. */
+    fatal: boolean;
+    /** Did the charge reproduce (oracle-grade) rather than stay a claim? */
+    reproduced: boolean;
+    /** Overturn depth at which it was surfaced (0 = base panel, ≥1 = deeper rounds). */
+    depthFound: number;
+}
+export interface PanelSeat {
+    role: string;
+    provider: string;
+}
+/** Map a provider id to its coarse vendor. */
+export declare function vendorOf(providerId: string): Vendor;
+/**
+ * Resolve the verdict from the surviving charges, applying the overturn window.
+ *
+ * THE OVERTURN MECHANIC: only charges surfaced at depth ≤ `overturnDepth` count.
+ * With `overturnDepth = 0` the deeper-review rounds are disabled, so a mutant a
+ * shallow pass missed (surfaced at depth ≥ 1) does NOT count and the verdict
+ * stays SHIP — which is exactly the false-SHIP the court exists to catch. With
+ * `overturnDepth ≥ 1` that same charge counts and flips the verdict. This
+ * asymmetry is the whole point: a SHIP must SURVIVE escalation.
+ */
+export declare function resolveVerdict(charges: Charge[], overturnDepth: number): Verdict;
+export interface PanelPolicy {
+    /** Minimum number of DISTINCT vendors on the panel (default 2). */
+    minVendors?: number;
+}
+/**
+ * Validate a seated panel against the court's anti-collusion invariants.
+ * Returns a list of violation codes (empty == valid).
+ *   - 'writerIsNeverJuror' : the jury shares a vendor with the writer/defense.
+ *   - 'vendor-diversity'   : fewer than `minVendors` distinct vendors seated.
+ */
+export declare function validatePanel(panel: PanelSeat[], policy?: PanelPolicy): string[];
+/**
+ * DoE-gated scoring: emit a numeric score ONLY when the operator asked for one
+ * AND the scoring rubric passed the ADR-122 ANOVA screen (it actually
+ * discriminates). Otherwise the court reports the verdict class + charges, never
+ * a noise "91/100".
+ */
+export declare function shouldEmitScore(rubricDoePassed: boolean, emitScore: boolean): boolean;
+//# sourceMappingURL=referee.d.ts.map