agentic-qe 3.12.2 → 3.13.0

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;

package/dist/shared/llm/provider-manager.d.ts

@@ -70,7 +70,7 @@ export declare class ProviderManager {
      */
     assertWithinBudget(input: string | Message[], options?: GenerateOptions | CompleteOptions): void;
     /** ADR-123: public spend recorder for those same bypassing callers. */
-    recordResponseSpend(response: LLMResponse): void;
+    recordResponseSpend(response: LLMResponse, agent?: string): void;
     /**
      * Generate text using the best available provider
      */

package/dist/shared/llm/provider-manager.js

@@ -18,6 +18,7 @@ import { createDefaultSpendLedger, InMemorySpendLedger, } from './spend-ledger';
 import { resolveBillingMode, billingNotice } from './billing-modes';
 import { ClaudeProvider } from './providers/claude';
 import { ClaudeCodeProvider } from './providers/claude-code';
+import { CodexProvider } from './providers/codex';
 import { CognitumProvider } from './providers/cognitum';
 import { OpenAIProvider } from './providers/openai';
 import { OllamaProvider } from './providers/ollama';
@@ -169,7 +170,7 @@ export class ProviderManager {
         }
     }
     /** ADR-123: persist a completed charge to the cross-process ledger. */
-    recordSpend(response) {
+    recordSpend(response, agent) {
         if (!this.spendLedger)
             return;
         this.spendLedger.record({
@@ -180,6 +181,7 @@ export class ProviderManager {
             promptTokens: response.usage.promptTokens,
             completionTokens: response.usage.completionTokens,
             requestId: response.requestId,
+            agent, // ADR-124 M2.3: per-agent attribution when the caller has context.
         });
     }
     /**
@@ -192,8 +194,8 @@ export class ProviderManager {
         this.enforceBudget(input, options);
     }
     /** ADR-123: public spend recorder for those same bypassing callers. */
-    recordResponseSpend(response) {
-        this.recordSpend(response);
+    recordResponseSpend(response, agent) {
+        this.recordSpend(response, agent);
     }
     /**
      * Generate text using the best available provider
@@ -417,6 +419,8 @@ export class ProviderManager {
                 return new ClaudeProvider(this.config.providers.claude);
             case 'claude-code':
                 return new ClaudeCodeProvider(this.config.providers['claude-code']);
+            case 'codex':
+                return new CodexProvider(this.config.providers.codex);
             case 'cognitum':
                 return new CognitumProvider(this.config.providers.cognitum);
             case 'openai':

package/dist/shared/llm/providers/claude-code.js

@@ -285,10 +285,19 @@ export class ClaudeCodeProvider {
                 clearTimeout(timer);
                 resolve({ code: code ?? 0, stdout, stderr });
             });
-            if (stdin !== undefined) {
-                child.stdin.write(stdin);
+            // EPIPE guard (qe-court finding): if `claude` exits before reading stdin,
+            // an unhandled 'error' on the stdin stream 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 — process handlers report the failure */
             }
-            child.stdin.end();
         });
     }
     /** Simple semaphore so we don't spawn unbounded `claude` subprocesses. */

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

@@ -0,0 +1,58 @@
+/**
+ * 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 { LLMProvider, LLMProviderType, BillingMode, CodexConfig, Message, GenerateOptions, EmbedOptions, CompleteOptions, LLMResponse, EmbeddingResponse, CompletionResponse, HealthCheckResult } from '../interfaces';
+export type { CodexConfig };
+/** Env vars whose presence could flip the CLI from subscription to API billing. */
+export declare const API_BILLING_ENV_VARS: readonly ["OPENAI_API_KEY", "CODEX_API_KEY"];
+/** Sentinel meaning "let Codex use its own configured default model". */
+export declare const CODEX_DEFAULT_MODEL = "default";
+export declare const DEFAULT_CODEX_CONFIG: CodexConfig;
+export declare class CodexProvider implements LLMProvider {
+    readonly type: LLMProviderType;
+    readonly name: string;
+    readonly billingMode: BillingMode;
+    private config;
+    private requestId;
+    private availabilityCache?;
+    private active;
+    private readonly queue;
+    constructor(config?: Partial<CodexConfig>);
+    isAvailable(): Promise<boolean>;
+    healthCheck(): Promise<HealthCheckResult>;
+    generate(input: string | Message[], options?: GenerateOptions): Promise<LLMResponse>;
+    embed(_text: string, _options?: EmbedOptions): Promise<EmbeddingResponse>;
+    complete(prompt: string, options?: CompleteOptions): Promise<CompletionResponse>;
+    getConfig(): CodexConfig;
+    getSupportedModels(): string[];
+    getCostPerToken(): {
+        input: number;
+        output: number;
+    };
+    dispose(): Promise<void>;
+    private flatten;
+    private classifyError;
+    /**
+     * Build the child env with API-billing keys stripped (LOAD-BEARING).
+     * Exported logic tested by parity/env-strip tests.
+     */
+    static childEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    private runProcess;
+    /** Simple semaphore so we don't spawn unbounded `codex` subprocesses. */
+    private withConcurrency;
+}
+//# sourceMappingURL=codex.d.ts.map