ghagga 3.2.0 → 3.3.0

package/dist/commands/review-blast-radius.test.js

@@ -0,0 +1,179 @@
+/**
+ * Unit tests for the blast-radius pure seams extracted from `reviewCommand`
+ * (design v2 D9): `resolveBlastRadiusEnabled`, `checkGraphStaleness`,
+ * `computeUncoveredLanguages`.
+ *
+ * `resolveBlastRadiusEnabled` touches the real filesystem (existsSync) — a
+ * REAL temp dir (mkdtempSync) is used, NOT a mocked `node:fs`, so the actual
+ * repoPath-relative resolution is exercised (CRITICAL-2 regression guard).
+ * This file deliberately does NOT `vi.mock('node:fs')` (unlike review.test.ts)
+ * to keep that guarantee honest.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GRAPH_VERSION } from 'ghagga-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { checkGraphStaleness, computeUncoveredLanguages, resolveBlastRadiusEnabled, } from './review.js';
+// ─── resolveBlastRadiusEnabled ───────────────────────────────────
+describe('resolveBlastRadiusEnabled', () => {
+    let repoPath;
+    let otherCwd;
+    beforeEach(() => {
+        repoPath = mkdtempSync(join(tmpdir(), 'ghagga-blast-radius-repo-'));
+        otherCwd = mkdtempSync(join(tmpdir(), 'ghagga-blast-radius-cwd-'));
+    });
+    afterEach(() => {
+        rmSync(repoPath, { recursive: true, force: true });
+        rmSync(otherCwd, { recursive: true, force: true });
+    });
+    function withGraph() {
+        mkdirSync(join(repoPath, '.ghagga'), { recursive: true });
+        writeFileSync(join(repoPath, '.ghagga', 'graph.json'), '{}');
+    }
+    it('auto-enables when .ghagga/graph.json exists under repoPath', () => {
+        withGraph();
+        const result = resolveBlastRadiusEnabled(repoPath, {}, {});
+        expect(result).toBe(true);
+    });
+    it('stays off when no graph.json exists', () => {
+        const result = resolveBlastRadiusEnabled(repoPath, {}, {});
+        expect(result).toBe(false);
+    });
+    it('resolves against repoPath, NOT process.cwd() (CRITICAL-2)', () => {
+        withGraph();
+        const originalCwd = process.cwd();
+        try {
+            process.chdir(otherCwd);
+            // The graph lives under repoPath, not the (different) current cwd —
+            // the v1 bug used resolve('.') and would have returned false here.
+            const result = resolveBlastRadiusEnabled(repoPath, {}, {});
+            expect(result).toBe(true);
+        }
+        finally {
+            process.chdir(originalCwd);
+        }
+    });
+    it('--no-blast-radius (blastRadius: false) wins over an existing graph', () => {
+        withGraph();
+        const result = resolveBlastRadiusEnabled(repoPath, { blastRadius: false }, {});
+        expect(result).toBe(false);
+    });
+    it('.ghagga.json enableBlastRadius: false wins over an existing graph', () => {
+        withGraph();
+        const result = resolveBlastRadiusEnabled(repoPath, {}, { enableBlastRadius: false });
+        expect(result).toBe(false);
+    });
+    it('.ghagga.json enableBlastRadius: true wins even without a graph', () => {
+        const result = resolveBlastRadiusEnabled(repoPath, {}, { enableBlastRadius: true });
+        expect(result).toBe(true);
+    });
+    it('explicit --no-blast-radius overrides .ghagga.json enableBlastRadius: true', () => {
+        const result = resolveBlastRadiusEnabled(repoPath, { blastRadius: false }, { enableBlastRadius: true });
+        expect(result).toBe(false);
+    });
+});
+// ─── checkGraphStaleness ──────────────────────────────────────────
+describe('checkGraphStaleness', () => {
+    function makeMetadata(overrides = {}) {
+        return {
+            lastIndexedCommit: 'abc123',
+            lastIndexedAt: new Date().toISOString(),
+            schemaVersion: GRAPH_VERSION,
+            fileCount: 1,
+            languages: ['typescript'],
+            indexDurationMs: 10,
+            ...overrides,
+        };
+    }
+    it('returns no warnings when metadata is fresh and HEAD matches', () => {
+        const metadata = makeMetadata({ lastIndexedCommit: 'abc123' });
+        expect(checkGraphStaleness(metadata, 'abc123')).toEqual([]);
+    });
+    it('warns on HEAD mismatch', () => {
+        const metadata = makeMetadata({ lastIndexedCommit: 'abc123' });
+        const warnings = checkGraphStaleness(metadata, 'def456');
+        expect(warnings.some((w) => w.kind === 'head-mismatch')).toBe(true);
+    });
+    it('skips the HEAD-mismatch check when currentHead is empty (non-git/detached)', () => {
+        const metadata = makeMetadata({ lastIndexedCommit: 'abc123' });
+        const warnings = checkGraphStaleness(metadata, '');
+        expect(warnings.some((w) => w.kind === 'head-mismatch')).toBe(false);
+    });
+    it('warns on age > 7 days', () => {
+        const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+        const metadata = makeMetadata({ lastIndexedCommit: 'abc123', lastIndexedAt: thirtyDaysAgo });
+        const warnings = checkGraphStaleness(metadata, 'abc123');
+        expect(warnings.some((w) => w.kind === 'stale-age')).toBe(true);
+    });
+    it('warns distinctly when metadata is null (B-005)', () => {
+        const warnings = checkGraphStaleness(null, 'abc123');
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]?.kind).toBe('no-metadata');
+    });
+    it('warns on graphVersion mismatch (B-003)', () => {
+        const metadata = makeMetadata({ lastIndexedCommit: 'abc123', graphVersion: GRAPH_VERSION + 1 });
+        const warnings = checkGraphStaleness(metadata, 'abc123');
+        expect(warnings.some((w) => w.kind === 'version-mismatch')).toBe(true);
+    });
+    it('does not warn on graphVersion match', () => {
+        const metadata = makeMetadata({ lastIndexedCommit: 'abc123', graphVersion: GRAPH_VERSION });
+        const warnings = checkGraphStaleness(metadata, 'abc123');
+        expect(warnings.some((w) => w.kind === 'version-mismatch')).toBe(false);
+    });
+});
+// ─── computeUncoveredLanguages ────────────────────────────────────
+describe('computeUncoveredLanguages', () => {
+    function makeGraph(nodeLanguages) {
+        return {
+            version: GRAPH_VERSION,
+            rootDir: '.',
+            nodes: Object.fromEntries(Object.entries(nodeLanguages).map(([path, language]) => [
+                path,
+                {
+                    hash: 'h',
+                    // biome-ignore lint/suspicious/noExplicitAny: fixture language is dynamic
+                    language: language,
+                    imports: [],
+                    exports: [],
+                    calls: [],
+                    isTest: false,
+                },
+            ])),
+        };
+    }
+    it('flags a changed file whose language has zero graph coverage', () => {
+        const graph = makeGraph({ 'src/main.go': 'go' });
+        const uncovered = computeUncoveredLanguages(graph, ['app.py']);
+        expect(uncovered).toContain('python');
+    });
+    it('does not flag a changed file whose language IS covered', () => {
+        const graph = makeGraph({ 'src/main.go': 'go' });
+        const uncovered = computeUncoveredLanguages(graph, ['src/other.go']);
+        expect(uncovered).not.toContain('go');
+    });
+    it('regex-fallback graph (languages populated from real nodes) is NOT all-flagged (CRITICAL-1)', () => {
+        // A regex-fallback-built graph still has real per-file `language` on
+        // every node (unlike dispatch's `indexedLanguages`, which is empty for
+        // the regex path) — so coverage must be computed from graph CONTENTS.
+        const graph = makeGraph({ 'src/a.ts': 'typescript', 'src/b.py': 'python' });
+        const uncovered = computeUncoveredLanguages(graph, ['src/a.ts', 'src/b.py']);
+        expect(uncovered).toEqual([]);
+    });
+    it('flags a subpackage-only language not present anywhere in the graph', () => {
+        const graph = makeGraph({ 'src/main.go': 'go' });
+        const uncovered = computeUncoveredLanguages(graph, [
+            'packages/api/requirements.txt',
+            'src/main.go',
+        ]);
+        // requirements.txt has no detectable language extension — must not crash
+        // and must not be spuriously flagged as a language.
+        expect(uncovered).toEqual([]);
+    });
+    it('flags multiple distinct uncovered languages without duplicates', () => {
+        const graph = makeGraph({ 'src/main.go': 'go' });
+        const uncovered = computeUncoveredLanguages(graph, ['a.py', 'b.py', 'c.rs']);
+        expect(uncovered.sort()).toEqual(['python', 'rust']);
+    });
+});
+//# sourceMappingURL=review-blast-radius.test.js.map

package/dist/commands/review-blast-radius.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-blast-radius.test.js","sourceRoot":"","sources":["../../src/commands/review-blast-radius.test.ts"],"names":[],"mappings":"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"}

package/dist/commands/review.d.ts

@@ -5,7 +5,7 @@
  * environment, and optional .ghagga.json file, then runs the
  * core review pipeline and formats the output.
  */
-import type { LLMProvider, ReviewMode } from 'ghagga-core';
+import type { DependencyGraph, GraphMetadata, LLMProvider, ReviewMode } from 'ghagga-core';
 export interface ReviewOptions {
     mode: ReviewMode;
     provider: LLMProvider;
@@ -53,6 +53,117 @@ export interface ReviewOptions {
     lenses?: string;
     /** Path to custom lens definitions directory (from --lens-dir flag). */
     lensDir?: string;
+    /**
+     * Explicit blast-radius override from `--no-blast-radius`. `false` forces
+     * blast-radius off regardless of graph presence / config; `undefined`
+     * defers to `.ghagga.json`/auto-detection (see `resolveBlastRadiusEnabled`).
+     */
+    blastRadius?: boolean;
+}
+/**
+ * A single entry in the `.ghagga.json` `providerChain` array — routes ONE
+ * multi-voice reviewer (consensus vote / fan-out lens) to a specific
+ * cross-engine target via mcp-llm-bridge. Mirrors `ghagga-core`'s
+ * `ProviderChainEntry`, minus `apiKey`: the gateway token is resolved at
+ * runtime (CLI `--api-key` / stored login token), never stored in plaintext
+ * in the config file.
+ */
+interface GhaggaConfigProviderChainEntry {
+    /** Only 'gateway' entries are meaningful for cross-engine routing. */
+    provider: 'gateway';
+    /** Model identifier passed to the bridge (e.g. "claude-sonnet-4-6"). */
+    model: string;
+    /**
+     * Bridge-side provider id to route to (e.g. 'cli-claude', 'codex-cli').
+     * Short-circuits the bridge's model-based routing.
+     */
+    targetProvider?: string;
+    /** Gateway base URL. Defaults to the first entry's / flat gateway config when omitted. */
+    gatewayUrl?: string;
+    /** OpenCode model in `provider/model` format (cli-bridge only — unused for gateway). */
+    cliModel?: string;
+}
+interface GhaggaConfig {
+    mode?: string;
+    provider?: string;
+    model?: string;
+    enableSemgrep?: boolean;
+    enableTrivy?: boolean;
+    enableCpd?: boolean;
+    customRules?: string[];
+    ignorePatterns?: string[];
+    reviewLevel?: string;
+    disabledTools?: string[];
+    enabledTools?: string[];
+    lenses?: string[];
+    /**
+     * Per-voice cross-engine provider chain (BL-CLI-PROVIDER-CHAIN). When set,
+     * consensus (3-vote) and fan-out (N-lens) modes round-robin each voice
+     * across these gateway entries instead of hammering a single engine.
+     */
+    providerChain?: GhaggaConfigProviderChainEntry[];
+    /**
+     * Enable blast-radius filtering (design v2 D7). `true`/`false` override
+     * auto-detection (`.ghagga/graph.json` presence); omit to auto-detect.
+     * `--no-blast-radius` (ReviewOptions.blastRadius === false) always wins
+     * over this config key.
+     */
+    enableBlastRadius?: boolean;
 }
 export declare function reviewCommand(targetPath: string, options: ReviewOptions): Promise<void>;
+/** One staleness/coverage signal for `checkGraphStaleness` — WARN, never block. */
+export interface StalenessWarning {
+    kind: 'head-mismatch' | 'stale-age' | 'no-metadata' | 'version-mismatch';
+    message: string;
+}
+/**
+ * Resolve whether blast-radius should be enabled for this review run.
+ *
+ * Precedence (highest to lowest):
+ *   1. `--no-blast-radius` (options.blastRadius === false) → OFF
+ *   2. `.ghagga.json` `enableBlastRadius` (explicit true/false) → that value
+ *   3. Auto-ON when `<repoPath>/.ghagga/graph.json` exists
+ *   4. OFF (no graph, no override)
+ *
+ * CRITICAL-2 (JD B-001): the existence check is resolved against `repoPath`
+ * — the review target — NOT `process.cwd()`, so `ghagga review <other-dir>`
+ * from an unrelated cwd still auto-detects correctly.
+ */
+export declare function resolveBlastRadiusEnabled(repoPath: string, options: Pick<ReviewOptions, 'blastRadius'>, fileConfig: Pick<GhaggaConfig, 'enableBlastRadius'>): boolean;
+/**
+ * Detect staleness/coverage-verification signals for the loaded graph.
+ * ALWAYS warn-and-continue (design v2 D2) — never blocks the review.
+ *
+ * - HEAD mismatch: `metadata.lastIndexedCommit` non-empty and differs from
+ *   `currentHead`. An EMPTY `currentHead` (non-git/detached checkout) skips
+ *   this specific check — there's nothing meaningful to compare against.
+ * - Age: delegates to `isGraphStale` (>`GRAPH_STALE_DAYS` days).
+ * - Metadata absent (B-005): `metadata === null` — graph.json loaded but no
+ *   sibling metadata.json (e.g. pre-feature `ghagga index` run). Returns
+ *   EARLY with only this warning — there's nothing else to check.
+ * - Version mismatch (B-003): `metadata.graphVersion` set and differs from
+ *   the current `GRAPH_VERSION` (equivalent to comparing against the loaded
+ *   graph's `version`, which `validateGraph` already pins to `GRAPH_VERSION`).
+ */
+export declare function checkGraphStaleness(metadata: GraphMetadata | null, currentHead: string): StalenessWarning[];
+/**
+ * Compute the set of languages present among `changedFiles` that have ZERO
+ * coverage in the loaded graph — i.e. files whose blast-radius dependent
+ * count is unreliable (shows zero, not "no dependents").
+ *
+ * Coverage is derived from the graph's ACTUAL node contents (design v2 D8,
+ * JD CRITICAL-1), not from indexer-dispatch bookkeeping:
+ *   - The regex-fallback path sets `indexedLanguages: []` even though every
+ *     node has a real `language` — keying off dispatch state would flag
+ *     every changed file as uncovered.
+ *   - `detectPresentLanguages` is root-only — a language that only exists in
+ *     a subpackage (e.g. `packages/api/requirements.txt`) is never detected
+ *     or skipped, so dispatch state gives no signal at all.
+ *
+ * Files whose language cannot be detected (`detectLanguage` returns
+ * `undefined` — unknown extension) are silently excluded; there is no
+ * language identity to report as uncovered.
+ */
+export declare function computeUncoveredLanguages(graph: DependencyGraph, changedFiles: string[]): string[];
+export {};
 //# sourceMappingURL=review.d.ts.map

package/dist/commands/review.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/commands/review.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EACV,WAAW,EAIX,UAAU,EAKX,MAAM,aAAa,CAAC;AA6CrB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IAC7C,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,aAAa,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IAEjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,yDAAyD;IACzD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,uDAAuD;IACvD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,yCAAyC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqBD,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAiQ7F"}
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/commands/review.ts"],"names":[],"mappings":"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"}

package/dist/commands/review.js

@@ -7,8 +7,9 @@
  */
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { buildSarif, DEFAULT_SETTINGS, EngramMemoryStorage, formatReviewComment, initializeDefaultTools, REVIEW_COMMENT_MARKER, reviewPipeline, SqliteMemoryStorage, toolRegistry, } from 'ghagga-core';
+import { buildSarif, DEFAULT_SETTINGS, detectLanguage, EngramMemoryStorage, FilesystemGraphLoader, formatReviewComment, GRAPH_VERSION, initializeDefaultTools, isGraphStale, NullGraphLoader, PreloadedGraphLoader, parseDiffFiles, REVIEW_COMMENT_MARKER, reviewPipeline, SqliteMemoryStorage, toolRegistry, } from 'ghagga-core';
 import { GitHubForgeAdapter, GitLabForgeAdapter, StaticTokenProvider, } from 'ghagga-forge';
 import { createCliGitHubClientPort, resolveGitHubRepoId } from '../lib/cli-github-client-port.js';
 import { createCliGitLabClientPort, resolveGitLabApiBase, resolveGitLabProjectId, } from '../lib/cli-gitlab-client-port.js';
@@ -94,6 +95,89 @@ export async function reviewCommand(targetPath, options) {
         const fileConfig = loadConfigFile(repoPath, options.config);
         // Step 3: Merge settings (CLI options take priority over config file)
         const settings = mergeSettings(options, fileConfig);
+        // Step 3.4: Resolve blast-radius auto-ON (design v2 D7) — resolved
+        // against repoPath (the review target), not process.cwd() (CRITICAL-2).
+        settings.enableBlastRadius = resolveBlastRadiusEnabled(repoPath, options, fileConfig);
+        // Step 3.4.5: Wire the local FilesystemGraphLoader + fs fileReader when
+        // blast-radius is enabled (design v2 D3/D4), and surface staleness
+        // (D2) + partial-language-coverage (D8) as advisory warnings — never
+        // blocking. Graph-absent is a silent no-op: applyBlastRadius itself
+        // already emits its own "no graph available" pipeline event.
+        //
+        // The graph is loaded exactly ONCE here (for staleness/coverage). The
+        // already-loaded result is then wrapped in a PreloadedGraphLoader (or
+        // NullGraphLoader when absent/malformed/oversize) so the pipeline's own
+        // `applyBlastRadius` step — which unconditionally calls
+        // `graphLoader.load()` — reads it from memory instead of re-reading
+        // graph.json (up to 20MB) and re-emitting the oversize/malformed warning
+        // a second time (R4-001).
+        let graphLoader;
+        let fileReader;
+        // Populated below (reusing the SAME `git rev-parse HEAD` already
+        // computed for staleness checking) and threaded into `ReviewInput` as
+        // `currentHead` — the Pillar 0 freshness precondition for
+        // symbol-precise blast-radius narrowing (scip-symbol-exclusion D0).
+        let currentHead;
+        if (settings.enableBlastRadius) {
+            const filesystemGraphLoader = new FilesystemGraphLoader(repoPath, {
+                onOversize: (bytes, max) => {
+                    tui.log.warn(`⚠️  Dependency graph exceeds ${max} bytes (actual: ${bytes}) — ignoring, blast-radius disabled for this run.`);
+                },
+                onMalformed: (reason) => {
+                    tui.log.warn(`⚠️  Dependency graph is stale/corrupt — ignoring (${reason}).`);
+                },
+            });
+            fileReader = async (filePath) => {
+                try {
+                    return await readFile(join(repoPath, filePath), 'utf-8');
+                }
+                catch {
+                    return null;
+                }
+            };
+            try {
+                const graph = await filesystemGraphLoader.load();
+                if (graph) {
+                    const metadata = await filesystemGraphLoader.loadMetadata();
+                    try {
+                        currentHead = execSync('git rev-parse HEAD', {
+                            cwd: repoPath,
+                            encoding: 'utf-8',
+                        }).trim();
+                    }
+                    catch {
+                        currentHead = '';
+                    }
+                    for (const warning of checkGraphStaleness(metadata, currentHead)) {
+                        tui.log.warn(`⚠️  ${warning.message}`);
+                    }
+                    const changedFiles = parseDiffFiles(diff).map((f) => f.path);
+                    const uncoveredLanguages = computeUncoveredLanguages(graph, changedFiles);
+                    if (uncoveredLanguages.length > 0) {
+                        tui.log.warn(`⚠️  Partial graph coverage: no indexed dependents for ${uncoveredLanguages.join(', ')} — ` +
+                            'blast-radius will show 0 dependents for these files, which may be unreliable rather than accurate.');
+                    }
+                    // Hand the pipeline the graph we already loaded — no re-read.
+                    graphLoader = new PreloadedGraphLoader(graph, metadata);
+                }
+                else {
+                    // Absent/malformed/oversize — filesystemGraphLoader already fired
+                    // its onOversize/onMalformed warning exactly once above. Hand the
+                    // pipeline a loader that always resolves to null so it degrades
+                    // without touching the filesystem again.
+                    graphLoader = new NullGraphLoader();
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                tui.log.warn(`⚠️  Blast-radius staleness/coverage check failed (continuing): ${message}`);
+                graphLoader = new NullGraphLoader();
+            }
+        }
+        // Step 3.5: Build the per-voice cross-engine provider chain, if configured
+        // (BL-CLI-PROVIDER-CHAIN). Undefined when absent — regression-safe, the
+        // pipeline falls back to the flat provider/model exactly as before.
+        const providerChain = buildProviderChain(fileConfig, options.apiKey);
         // Step 4: Show progress
         if (!options.outputFormat) {
             tui.intro('🤖 GHAGGA Code Review');
@@ -197,6 +281,18 @@ export async function reviewCommand(targetPath, options) {
             enhance: options.enhance,
             // --quick: disable AI review, use static analysis only
             ...(options.quick ? { aiReviewEnabled: false } : {}),
+            // Per-voice cross-engine routing (BL-CLI-PROVIDER-CHAIN) — undefined
+            // when `.ghagga.json` has no providerChain, unchanged flat-provider path.
+            ...(providerChain ? { providerChain } : {}),
+            // Blast-radius (design v2) — undefined when disabled/no graph, matching
+            // the pre-existing `applyBlastRadius` gate (`enableBlastRadius && graphLoader`).
+            ...(graphLoader ? { graphLoader } : {}),
+            ...(fileReader ? { fileReader } : {}),
+            // Pillar 0 freshness precondition (scip-symbol-exclusion D0) — reuses
+            // the SAME `git rev-parse HEAD` already computed above for staleness
+            // checking. Undefined when blast-radius is disabled or HEAD couldn't
+            // be resolved (non-git repo) — narrowing degrades to a no-op.
+            ...(currentHead ? { currentHead } : {}),
         });
         // Step 5.5: Persist memory to disk
         await memoryStorage?.close();
@@ -544,6 +640,39 @@ function getGitDiff(repoPath) {
     }
 }
 // ─── Config File ────────────────────────────────────────────────
+/**
+ * Validate the shape of a `.ghagga.json` `providerChain` array. Throws a
+ * descriptive `Error` on the first invalid entry — provider misrouting is
+ * high-stakes (silently reviewing with the wrong engine), so this fails
+ * loudly rather than the soft-warn-and-continue behavior used for a
+ * generally malformed config file.
+ */
+function validateProviderChain(chain) {
+    if (!Array.isArray(chain)) {
+        throw new Error('providerChain must be an array');
+    }
+    chain.forEach((rawEntry, index) => {
+        if (typeof rawEntry !== 'object' || rawEntry === null) {
+            throw new Error(`providerChain[${index}] must be an object`);
+        }
+        const entry = rawEntry;
+        if (entry.provider !== 'gateway') {
+            throw new Error(`providerChain[${index}].provider must be "gateway" (got ${JSON.stringify(entry.provider)})`);
+        }
+        if (typeof entry.model !== 'string' || entry.model.length === 0) {
+            throw new Error(`providerChain[${index}].model must be a non-empty string`);
+        }
+        if (entry.targetProvider !== undefined && typeof entry.targetProvider !== 'string') {
+            throw new Error(`providerChain[${index}].targetProvider must be a string`);
+        }
+        if (entry.gatewayUrl !== undefined && typeof entry.gatewayUrl !== 'string') {
+            throw new Error(`providerChain[${index}].gatewayUrl must be a string`);
+        }
+        if (entry.cliModel !== undefined && typeof entry.cliModel !== 'string') {
+            throw new Error(`providerChain[${index}].cliModel must be a string`);
+        }
+    });
+}
 /**
  * Load and parse an optional .ghagga.json config file.
  */
@@ -552,15 +681,148 @@ function loadConfigFile(repoPath, configPath) {
     if (!existsSync(filePath)) {
         return {};
     }
+    let parsed;
     try {
         const raw = readFileSync(filePath, 'utf-8');
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         tui.log.warn(`⚠️  Could not parse config file: ${message}`);
         return {};
     }
+    if (parsed.providerChain !== undefined) {
+        try {
+            validateProviderChain(parsed.providerChain);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            tui.log.error(`❌ Invalid .ghagga.json providerChain: ${message}`);
+            process.exit(1);
+            return {};
+        }
+    }
+    return parsed;
+}
+/**
+ * Map a validated `.ghagga.json` providerChain into `ghagga-core`'s
+ * `ProviderChainEntry[]` for `ReviewInput.providerChain` — the piece that
+ * closes the CLI's gap in per-voice cross-engine routing (consensus/fan-out
+ * modes round-robin each voice across these gateway entries, see
+ * `resolveGenerateTextFns` in `packages/core/src/pipeline/providers.ts`).
+ *
+ * `apiKey` is NEVER read from the config file (never stored in plaintext) —
+ * it is filled at runtime from the resolved gateway token (`options.apiKey`,
+ * itself CLI flag > env var > stored login token, see `apps/cli/src/index.ts`).
+ */
+function buildProviderChain(fileConfig, apiKey) {
+    if (!fileConfig.providerChain || fileConfig.providerChain.length === 0) {
+        return undefined;
+    }
+    return fileConfig.providerChain.map((entry) => ({
+        provider: entry.provider,
+        model: entry.model,
+        apiKey: apiKey ?? '',
+        ...(entry.targetProvider !== undefined ? { targetProvider: entry.targetProvider } : {}),
+        ...(entry.gatewayUrl !== undefined ? { gatewayUrl: entry.gatewayUrl } : {}),
+        ...(entry.cliModel !== undefined ? { cliModel: entry.cliModel } : {}),
+    }));
+}
+/**
+ * Resolve whether blast-radius should be enabled for this review run.
+ *
+ * Precedence (highest to lowest):
+ *   1. `--no-blast-radius` (options.blastRadius === false) → OFF
+ *   2. `.ghagga.json` `enableBlastRadius` (explicit true/false) → that value
+ *   3. Auto-ON when `<repoPath>/.ghagga/graph.json` exists
+ *   4. OFF (no graph, no override)
+ *
+ * CRITICAL-2 (JD B-001): the existence check is resolved against `repoPath`
+ * — the review target — NOT `process.cwd()`, so `ghagga review <other-dir>`
+ * from an unrelated cwd still auto-detects correctly.
+ */
+export function resolveBlastRadiusEnabled(repoPath, options, fileConfig) {
+    if (options.blastRadius === false)
+        return false;
+    if (fileConfig.enableBlastRadius === false)
+        return false;
+    if (fileConfig.enableBlastRadius === true)
+        return true;
+    return existsSync(join(repoPath, '.ghagga', 'graph.json'));
+}
+/**
+ * Detect staleness/coverage-verification signals for the loaded graph.
+ * ALWAYS warn-and-continue (design v2 D2) — never blocks the review.
+ *
+ * - HEAD mismatch: `metadata.lastIndexedCommit` non-empty and differs from
+ *   `currentHead`. An EMPTY `currentHead` (non-git/detached checkout) skips
+ *   this specific check — there's nothing meaningful to compare against.
+ * - Age: delegates to `isGraphStale` (>`GRAPH_STALE_DAYS` days).
+ * - Metadata absent (B-005): `metadata === null` — graph.json loaded but no
+ *   sibling metadata.json (e.g. pre-feature `ghagga index` run). Returns
+ *   EARLY with only this warning — there's nothing else to check.
+ * - Version mismatch (B-003): `metadata.graphVersion` set and differs from
+ *   the current `GRAPH_VERSION` (equivalent to comparing against the loaded
+ *   graph's `version`, which `validateGraph` already pins to `GRAPH_VERSION`).
+ */
+export function checkGraphStaleness(metadata, currentHead) {
+    if (!metadata) {
+        return [
+            {
+                kind: 'no-metadata',
+                message: 'Graph loaded but no metadata found — staleness cannot be verified; re-run `ghagga index`.',
+            },
+        ];
+    }
+    const warnings = [];
+    if (currentHead && metadata.lastIndexedCommit && metadata.lastIndexedCommit !== currentHead) {
+        warnings.push({
+            kind: 'head-mismatch',
+            message: `Dependency graph indexed at ${metadata.lastIndexedCommit}, HEAD is ${currentHead} — run \`ghagga index\` to refresh.`,
+        });
+    }
+    if (isGraphStale(metadata)) {
+        warnings.push({
+            kind: 'stale-age',
+            message: `Dependency graph is stale (last indexed: ${metadata.lastIndexedAt}) — run \`ghagga index\` to refresh.`,
+        });
+    }
+    if (metadata.graphVersion !== undefined && metadata.graphVersion !== GRAPH_VERSION) {
+        warnings.push({
+            kind: 'version-mismatch',
+            message: `Graph metadata schema version (${metadata.graphVersion}) does not match the current graph version (${GRAPH_VERSION}) — run \`ghagga index\` to refresh.`,
+        });
+    }
+    return warnings;
+}
+/**
+ * Compute the set of languages present among `changedFiles` that have ZERO
+ * coverage in the loaded graph — i.e. files whose blast-radius dependent
+ * count is unreliable (shows zero, not "no dependents").
+ *
+ * Coverage is derived from the graph's ACTUAL node contents (design v2 D8,
+ * JD CRITICAL-1), not from indexer-dispatch bookkeeping:
+ *   - The regex-fallback path sets `indexedLanguages: []` even though every
+ *     node has a real `language` — keying off dispatch state would flag
+ *     every changed file as uncovered.
+ *   - `detectPresentLanguages` is root-only — a language that only exists in
+ *     a subpackage (e.g. `packages/api/requirements.txt`) is never detected
+ *     or skipped, so dispatch state gives no signal at all.
+ *
+ * Files whose language cannot be detected (`detectLanguage` returns
+ * `undefined` — unknown extension) are silently excluded; there is no
+ * language identity to report as uncovered.
+ */
+export function computeUncoveredLanguages(graph, changedFiles) {
+    const covered = new Set(Object.values(graph.nodes).map((node) => node.language));
+    const uncovered = new Set();
+    for (const filePath of changedFiles) {
+        const language = detectLanguage(filePath);
+        if (language && !covered.has(language)) {
+            uncovered.add(language);
+        }
+    }
+    return [...uncovered];
 }
 // ─── Settings Merge ─────────────────────────────────────────────
 /**