agentic-qe 3.15.9 → 3.15.10

package/dist/mcp/tools/learning-optimization/dream.js

@@ -13,6 +13,7 @@
  */
 import { MCPToolBase, getSharedMemoryBackend } from '../base.js';
 import { createDreamEngine, } from '../../../learning/dream/index.js';
+import { DreamAlreadyRunningError } from '../../../learning/dream/dream-engine.js';
 import { createQEReasoningBank } from '../../../learning/qe-reasoning-bank.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 // ============================================================================
@@ -66,39 +67,37 @@ export class DreamCycleTool extends MCPToolBase {
         timeout: 120000, // 2 minutes max (dream cycle + overhead)
     };
     engine = null;
-    engineConfig = null;
+    /** #1060: the one in-flight engine creation, so concurrent calls share it. */
+    enginePending = null;
     /**
      * Get or create the DreamEngine instance.
      *
-     * If config differs from the cached engine's config, the engine is
-     * recreated to respect the new configuration. This prevents the bug
-     * where subsequent calls with different durationMs/minPatterns were ignored.
+     * #1060: one engine for the tool's lifetime. Duration and the minimum
+     * concept count are passed per call to dream(), so a call with different
+     * values no longer closes and recreates the engine (which interrupted a
+     * dream still running on it).
      */
-    async getEngine(config) {
-        // Check if we need to recreate due to config change
-        const configChanged = this.engine && config && !this.configsEqual(this.engineConfig, config);
-        if (configChanged && this.engine) {
-            await this.engine.close().catch(() => { });
-            this.engine = null;
-            this.engineConfig = null;
-        }
-        if (!this.engine) {
-            this.engine = createDreamEngine(config);
-            this.engineConfig = config || null;
-            await this.engine.initialize();
+    async getEngine() {
+        if (this.engine)
+            return this.engine;
+        if (!this.enginePending) {
+            const create = async () => {
+                const engine = createDreamEngine();
+                await engine.initialize();
+                // A reset while initializing dropped this engine; don't resurrect it.
+                if (this.enginePending === pending)
+                    this.engine = engine;
+                else
+                    engine.close().catch(() => { });
+                return engine;
+            };
+            const pending = create();
+            this.enginePending = pending;
+            const settle = () => { if (this.enginePending === pending)
+                this.enginePending = null; };
+            pending.then(settle, settle);
         }
-        return this.engine;
-    }
-    /**
-     * Compare two configs for equality (shallow comparison of relevant fields)
-     */
-    configsEqual(a, b) {
-        if (a === b)
-            return true;
-        if (!a || !b)
-            return false;
-        return (a.maxDurationMs === b.maxDurationMs &&
-            a.minConceptsRequired === b.minConceptsRequired);
+        return this.enginePending;
     }
     /**
      * Load patterns from ReasoningBank into the DreamEngine
@@ -142,7 +141,8 @@ export class DreamCycleTool extends MCPToolBase {
                 domain: result.pattern.qeDomain || 'learning-optimization',
                 patternType: result.pattern.patternType,
                 confidence: result.pattern.confidence,
-                successRate: result.pattern.successRate || 0.5,
+                // A real 0% stays 0%; a pattern never used has no rate (#1142 review).
+                successRate: result.pattern.usageCount > 0 ? result.pattern.successRate : undefined,
             }));
             const loaded = await engine.loadPatternsAsConcepts(importPatterns);
             this.logger.info(`Loaded ${loaded} patterns as concepts from ReasoningBank`);
@@ -195,17 +195,19 @@ export class DreamCycleTool extends MCPToolBase {
         const minPatterns = params.minPatterns || 10;
         const loadFromRB = params.loadFromReasoningBank !== false;
         this.logger.info(`Starting dream cycle (${durationMs}ms, min: ${minPatterns} patterns)`);
-        const engine = await this.getEngine({
-            maxDurationMs: durationMs,
-            minConceptsRequired: minPatterns,
-        });
+        const engine = await this.getEngine();
+        // #1060: a concurrent dream is refused with a clear error, not queued.
+        const running = engine.getCurrentCycle();
+        if (running) {
+            throw new DreamAlreadyRunningError(running.id);
+        }
         // Load patterns from ReasoningBank if requested
         if (loadFromRB) {
             const loaded = await this.loadPatternsFromReasoningBank(engine);
             this.logger.info(`Loaded ${loaded} patterns from ReasoningBank`);
         }
         // Run the dream cycle
-        const result = await engine.dream(durationMs);
+        const result = await engine.dream(durationMs, { minConceptsRequired: minPatterns });
         const dreamResult = {
             cycleId: result.cycle.id,
             status: result.cycle.status,
@@ -215,6 +217,7 @@ export class DreamCycleTool extends MCPToolBase {
             insightsGenerated: result.cycle.insightsGenerated,
             activationStats: result.activationStats,
             patternsCreated: result.patternsCreated,
+            commitDurationMs: result.commitDurationMs,
         };
         const insights = result.insights.map((i) => ({
             id: i.id,
@@ -392,6 +395,7 @@ export class DreamCycleTool extends MCPToolBase {
      * Reset instance cache (for fleet dispose)
      */
     resetInstanceCache() {
+        this.enginePending = null;
         if (this.engine) {
             this.engine.close().catch(console.error);
             this.engine = null;

package/dist/mcp/tools/learning-optimization/optimize.d.ts

@@ -44,6 +44,8 @@ export interface LearnResult {
     measuredExperiences?: number;
     /** #1109: experiences recorded with an assigned reward, excluded from every rate. */
     assignedRewardsExcluded?: number;
+    /** #1121: requested experience IDs with no stored experience; not processed. */
+    experienceIdsNotFound?: number;
     evidenceStatus?: 'insufficient-evidence';
     patternsLearned: number;
     newPatterns: LearnedPattern[];
@@ -103,8 +105,14 @@ export interface PatternResult {
     byType: Record<string, number>;
     byDomain: Record<string, number>;
     topPatterns: LearnedPattern[];
-    avgConfidence: number;
-    avgSuccessRate: number;
+    /** Null when no pattern has a measured rate (#1121); not a 0 that reads as measured. */
+    avgConfidence: number | null;
+    avgSuccessRate: number | null;
+    /** #1109: patterns learned from assigned rewards, left out of every figure. */
+    assignedPatternsExcluded?: number;
+    /** #1121: untagged patterns mined before #1120, left out of every figure. */
+    legacyPatternsExcluded?: number;
+    evidenceStatus?: 'insufficient-evidence';
     /** Read-only persisted SONA visibility when an initialized fleet is available. */
     sona?: SONASnapshot;
 }
@@ -118,6 +126,8 @@ export interface DashboardResult {
     assignedRewardsExcluded?: number;
     /** #1109: stored patterns excluded because they were learned from assigned rewards. */
     assignedPatternsExcluded?: number;
+    /** #1121: untagged patterns mined before #1120 (rate selected over successes), excluded likewise. */
+    legacyPatternsExcluded?: number;
     /** Ranked by measured success rate; empty when no domain has a measured outcome. */
     topPerformingDomains: DomainName[];
     evidenceStatus?: 'insufficient-evidence';
@@ -150,6 +160,12 @@ export declare class LearningOptimizeTool extends MCPToolBase<LearningOptimizePa
     private getServices;
     execute(params: LearningOptimizeParams, context: MCPToolContext): Promise<ToolResult<LearningOptimizeResult>>;
     private executeLearn;
+    /**
+     * #1121: learn from explicitly requested experiences. experiencesProcessed
+     * is the number actually read; IDs with no stored experience are counted in
+     * experienceIdsNotFound instead of being reported as processed.
+     */
+    private learnFromExperienceIds;
     /**
      * Return demo learn results when no real data available.
      * Only used when demoMode is explicitly requested or as fallback with warning.

package/dist/mcp/tools/learning-optimization/optimize.js

@@ -80,6 +80,9 @@ export class LearningOptimizeTool extends MCPToolBase {
                     break;
                 case 'patterns':
                     result.patternResult = await this.executePatterns(domain, context);
+                    if (result.patternResult.evidenceStatus === 'insufficient-evidence') {
+                        result.evidenceStatus = 'insufficient-evidence';
+                    }
                     break;
                 case 'dashboard':
                     result.dashboardResult = await this.executeDashboard(context);
@@ -116,7 +119,11 @@ export class LearningOptimizeTool extends MCPToolBase {
             status: 'learning',
             message: `Learning from ${experienceIds?.length || 'recent'} experiences`,
         });
-        // Get experiences from memory or mine recent ones
+        // #1121: learn from the requested experiences; count only those read.
+        if (experienceIds && experienceIds.length > 0) {
+            return this.learnFromExperienceIds(learningCoordinator, experienceIds);
+        }
+        // Mine recent experiences
         const timeRange = TimeRange.lastNDays(7);
         const mineResult = await learningCoordinator.mineExperiences(targetDomain, timeRange);
         const newPatterns = [];
@@ -143,10 +150,6 @@ export class LearningOptimizeTool extends MCPToolBase {
                 });
             }
         }
-        // If specific experience IDs provided, record them
-        if (experienceIds && experienceIds.length > 0) {
-            experiencesProcessed = experienceIds.length;
-        }
         // If no patterns were learned, return empty result (not fake data)
         // This is a valid state - no patterns discovered yet
         // #1109: there is no recorded baseline, so improvement is never computed
@@ -161,6 +164,42 @@ export class LearningOptimizeTool extends MCPToolBase {
             unmeasured: ['improvement'],
         };
     }
+    /**
+     * #1121: learn from explicitly requested experiences. experiencesProcessed
+     * is the number actually read; IDs with no stored experience are counted in
+     * experienceIdsNotFound instead of being reported as processed.
+     */
+    async learnFromExperienceIds(learningCoordinator, experienceIds) {
+        const readResult = await learningCoordinator.getExperiencesByIds(experienceIds);
+        if (!readResult.success)
+            throw readResult.error;
+        const read = readResult.value;
+        const { measured, assignedExcluded } = partitionByRewardSource(read);
+        const learned = measured.length > 0 ? await learningCoordinator.learnPattern(read) : null;
+        const newPatterns = learned?.success
+            ? [{
+                    id: learned.value.id,
+                    type: learned.value.type,
+                    name: learned.value.name,
+                    description: learned.value.description,
+                    confidence: learned.value.confidence,
+                    usageCount: learned.value.usageCount,
+                    successRate: learned.value.successRate,
+                }]
+            : [];
+        this.markAsRealData();
+        return {
+            experiencesProcessed: read.length,
+            experienceIdsNotFound: new Set(experienceIds).size - read.length,
+            measuredExperiences: measured.length,
+            assignedRewardsExcluded: assignedExcluded,
+            ...(measured.length === 0 ? { evidenceStatus: 'insufficient-evidence' } : {}),
+            patternsLearned: newPatterns.length,
+            newPatterns,
+            improvement: null,
+            unmeasured: ['improvement'],
+        };
+    }
     /**
      * Return demo learn results when no real data available.
      * Only used when demoMode is explicitly requested or as fallback with warning.
@@ -360,14 +399,15 @@ export class LearningOptimizeTool extends MCPToolBase {
         // Get pattern statistics from the real service
         const statsResult = await learningCoordinator.getPatternStats(domain);
         if (!statsResult.success) {
-            // Return empty stats on failure
+            // Stats could not be read: nothing is measured, so no averages (#1121).
             return {
                 totalPatterns: 0,
                 byType: {},
                 byDomain: {},
                 topPatterns: [],
-                avgConfidence: 0,
-                avgSuccessRate: 0,
+                avgConfidence: null,
+                avgSuccessRate: null,
+                evidenceStatus: 'insufficient-evidence',
                 sona,
             };
         }
@@ -382,13 +422,17 @@ export class LearningOptimizeTool extends MCPToolBase {
             usageCount: p.usageCount,
             successRate: p.successRate,
         }));
+        const measured = stats.totalPatterns > 0;
         return {
             totalPatterns: stats.totalPatterns,
             byType: stats.byType,
             byDomain: stats.byDomain,
             topPatterns,
-            avgConfidence: stats.avgConfidence,
-            avgSuccessRate: stats.avgSuccessRate,
+            avgConfidence: measured ? stats.avgConfidence : null,
+            avgSuccessRate: measured ? stats.avgSuccessRate : null,
+            ...(stats.assignedPatternsExcluded ? { assignedPatternsExcluded: stats.assignedPatternsExcluded } : {}),
+            ...(stats.legacyPatternsExcluded ? { legacyPatternsExcluded: stats.legacyPatternsExcluded } : {}),
+            ...(measured ? {} : { evidenceStatus: 'insufficient-evidence' }),
             sona,
         };
     }
@@ -438,6 +482,9 @@ export class LearningOptimizeTool extends MCPToolBase {
         const assignedPatternsExcluded = statsResult.success
             ? statsResult.value.assignedPatternsExcluded ?? 0
             : 0;
+        const legacyPatternsExcluded = statsResult.success
+            ? statsResult.value.legacyPatternsExcluded ?? 0
+            : 0;
         const avgSuccessRate = totalPatterns > 0 && statsResult.success
             ? statsResult.value.avgSuccessRate
             : null;
@@ -491,6 +538,7 @@ export class LearningOptimizeTool extends MCPToolBase {
             experiencesLast24h,
             ...(assignedRewardsExcluded > 0 ? { assignedRewardsExcluded } : {}),
             ...(assignedPatternsExcluded > 0 ? { assignedPatternsExcluded } : {}),
+            ...(legacyPatternsExcluded > 0 ? { legacyPatternsExcluded } : {}),
             topPerformingDomains,
             ...(unmeasured.length > 0
                 ? { evidenceStatus: 'insufficient-evidence', unmeasured }

package/dist/mcp/tools/quality-assessment/gate.js

@@ -11,6 +11,8 @@
  */
 import { MCPToolBase } from '../base.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
+import { MAX_PAYLOAD_FILE_BYTES, requirePayloadPath } from '../../../shared/io/payload-path-guard.js';
+import { findProjectRoot } from '../../../kernel/project-root.js';
 import { getLLMRouter } from '../base.js';
 import { runQualityGate, } from '../../../validation/quality-gate-runner.js';
 import { createRouterFrontierJudge, createUnavailableJudge, } from '../../../validation/frontier-judge.js';
@@ -32,6 +34,15 @@ export class QualityGateTool extends MCPToolBase {
             if (typeof params.artifact !== 'string' || params.artifact.length === 0) {
                 return { success: false, error: 'artifact (non-empty string) is required' };
             }
+            // #1126: a caller-named anchor must be a regular file inside the project
+            // (relative paths resolve against the project root, as the runner does).
+            let anchorPath;
+            if (params.anchorPath !== undefined) {
+                const confined = await requirePayloadPath('qe/quality/gate', 'anchorPath', params.anchorPath, { basePath: findProjectRoot(), maxBytes: MAX_PAYLOAD_FILE_BYTES });
+                if (!confined.success)
+                    return { success: false, error: confined.error.message };
+                anchorPath = confined.value;
+            }
             const router = await getLLMRouter(context);
             const judge = router
                 ? createRouterFrontierJudge(router, {
@@ -47,7 +58,7 @@ export class QualityGateTool extends MCPToolBase {
                 artifact: params.artifact,
                 checklistId: params.checklistId,
                 judge,
-                anchorPath: params.anchorPath,
+                anchorPath,
                 verificationManifest: params.verificationManifest,
             });
             return { success: true, data: result };

package/dist/mcp/tools/requirements-validation/quality-criteria.js

@@ -15,6 +15,7 @@ import { MCPToolBase } from '../base.js';
 import { createQualityCriteriaService, HTSM_CATEGORIES, NEVER_OMIT_CATEGORIES, } from '../../../domains/requirements-validation/index.js';
 import { existsSync, readFileSync } from 'fs';
 import { toErrorMessage } from '../../../shared/error-utils.js';
+import { MAX_PAYLOAD_FILE_BYTES, requirePayloadPath } from '../../../shared/io/payload-path-guard.js';
 // ============================================================================
 // Tool Implementation
 // ============================================================================
@@ -121,8 +122,14 @@ export class QualityCriteriaTool extends MCPToolBase {
             });
             // Load epic content
             let content = epicContent || '';
-            if (epicPath && existsSync(epicPath)) {
-                content = readFileSync(epicPath, 'utf-8');
+            // #1126: the epic is returned verbatim in the agent prompt, so read it
+            // only from a regular file inside the project.
+            if (epicPath) {
+                const confined = await requirePayloadPath('quality-criteria', 'epicPath', epicPath, { allowMissing: true, maxBytes: MAX_PAYLOAD_FILE_BYTES });
+                if (!confined.success)
+                    return { success: false, error: confined.error.message };
+                if (existsSync(confined.value))
+                    content = readFileSync(confined.value, 'utf-8');
             }
             if (!content && !epicPath) {
                 return {

package/dist/migration/agent-compat.js

@@ -7,6 +7,7 @@
  * @module migration/agent-compat
  * @see docs/adr/adr-048-agent-naming-conventions.md
  */
+import { getOwn } from '../shared/utils/safe-record.js';
 /**
  * Complete mapping of deprecated V2 agent names to their V3 equivalents with domain info.
  *
@@ -127,7 +128,8 @@ export const v2AgentMapping = Object.fromEntries(Object.entries(v2AgentMappingWi
  * ```
  */
 export function resolveAgentName(name) {
-    return v2AgentMapping[name] ?? name;
+    // #1136: own entries only; `constructor` is not a V2 agent name.
+    return getOwn(v2AgentMapping, name) ?? name;
 }
 /**
  * Checks if an agent name is a deprecated V2 agent.
@@ -146,7 +148,7 @@ export function resolveAgentName(name) {
  * ```
  */
 export function isDeprecatedAgent(name) {
-    return name in v2AgentMapping;
+    return Object.hasOwn(v2AgentMapping, name);
 }
 /**
  * Generates a deprecation warning message for a V2 agent name.
@@ -170,7 +172,7 @@ export function isDeprecatedAgent(name) {
  * ```
  */
 export function getDeprecationWarning(v2Name) {
-    const v3Name = v2AgentMapping[v2Name];
+    const v3Name = getOwn(v2AgentMapping, v2Name);
     if (!v3Name) {
         return '';
     }
@@ -211,7 +213,7 @@ export const v3Agents = [
  */
 export function getAgentDomain(agentName) {
     // Check V2 mapping
-    const v2Entry = v2AgentMappingWithDomain[agentName];
+    const v2Entry = getOwn(v2AgentMappingWithDomain, agentName);
     if (v2Entry) {
         return v2Entry.domain;
     }
@@ -261,7 +263,7 @@ export function generateMigrationReport(usedAgents) {
     const alreadyV3 = [];
     const unknown = [];
     for (const agent of usedAgents) {
-        const v2Entry = v2AgentMappingWithDomain[agent];
+        const v2Entry = getOwn(v2AgentMappingWithDomain, agent);
         if (v2Entry) {
             needsMigration.push({
                 v2Name: agent,

package/dist/migrations/20261018_add_dream_insights_archive.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agentic QE v3 - Dream insights archive table (#1066, #1116)
+ *
+ * The dream_insights retention sweep copies each stale insight here before it
+ * deletes it (#1066). Until #1116 the sweep created the table lazily on its
+ * first run, outside the versioned schema; it is now created by the v14
+ * migration.
+ *
+ * Additive and idempotent: `CREATE ... IF NOT EXISTS` only, so a database where
+ * an earlier sweep already created the table (with its rows) is left as it
+ * is, and an older AQE that still creates it lazily with the same statement
+ * keeps working on a migrated database.
+ *
+ * Same columns as dream_insights plus archive_id and archived_at. `id` is not
+ * unique here: an insight that comes back (for example from a brain import)
+ * and is swept again gets a second row instead of replacing the first. No
+ * foreign key, so deleting a dream cycle does not cascade into the archive.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+export declare const MIGRATION_VERSION = "20261018_add_dream_insights_archive";
+export declare const DREAM_INSIGHTS_ARCHIVE_TABLE = "dream_insights_archive";
+/** The table, exactly as the 3.15.9 sweep created it lazily. */
+export declare const DREAM_INSIGHTS_ARCHIVE_TABLE_SQL = "\n  CREATE TABLE IF NOT EXISTS dream_insights_archive (\n    archive_id INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL,\n    cycle_id TEXT,\n    insight_type TEXT,\n    source_concepts TEXT,\n    description TEXT,\n    novelty_score REAL,\n    confidence_score REAL,\n    actionable INTEGER,\n    applied INTEGER,\n    suggested_action TEXT,\n    pattern_id TEXT,\n    created_at TEXT,\n    archived_at TEXT NOT NULL DEFAULT (datetime('now'))\n  )\n";
+export declare const DREAM_INSIGHTS_ARCHIVE_SCHEMA = "\n  \n  CREATE TABLE IF NOT EXISTS dream_insights_archive (\n    archive_id INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL,\n    cycle_id TEXT,\n    insight_type TEXT,\n    source_concepts TEXT,\n    description TEXT,\n    novelty_score REAL,\n    confidence_score REAL,\n    actionable INTEGER,\n    applied INTEGER,\n    suggested_action TEXT,\n    pattern_id TEXT,\n    created_at TEXT,\n    archived_at TEXT NOT NULL DEFAULT (datetime('now'))\n  )\n;\n  -- The sweep's read-back looks copies up by insight id.\n  CREATE INDEX IF NOT EXISTS idx_dream_insights_archive_id ON dream_insights_archive(id);\n";
+export declare function applyMigration(db: DatabaseType): void;
+export declare function isMigrationApplied(db: DatabaseType): boolean;
+//# sourceMappingURL=20261018_add_dream_insights_archive.d.ts.map

package/dist/migrations/20261018_add_dream_insights_archive.js

@@ -0,0 +1,57 @@
+/**
+ * Agentic QE v3 - Dream insights archive table (#1066, #1116)
+ *
+ * The dream_insights retention sweep copies each stale insight here before it
+ * deletes it (#1066). Until #1116 the sweep created the table lazily on its
+ * first run, outside the versioned schema; it is now created by the v14
+ * migration.
+ *
+ * Additive and idempotent: `CREATE ... IF NOT EXISTS` only, so a database where
+ * an earlier sweep already created the table (with its rows) is left as it
+ * is, and an older AQE that still creates it lazily with the same statement
+ * keeps working on a migrated database.
+ *
+ * Same columns as dream_insights plus archive_id and archived_at. `id` is not
+ * unique here: an insight that comes back (for example from a brain import)
+ * and is swept again gets a second row instead of replacing the first. No
+ * foreign key, so deleting a dream cycle does not cascade into the archive.
+ */
+export const MIGRATION_VERSION = '20261018_add_dream_insights_archive';
+export const DREAM_INSIGHTS_ARCHIVE_TABLE = 'dream_insights_archive';
+/** The table, exactly as the 3.15.9 sweep created it lazily. */
+export const DREAM_INSIGHTS_ARCHIVE_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS ${DREAM_INSIGHTS_ARCHIVE_TABLE} (
+    archive_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL,
+    cycle_id TEXT,
+    insight_type TEXT,
+    source_concepts TEXT,
+    description TEXT,
+    novelty_score REAL,
+    confidence_score REAL,
+    actionable INTEGER,
+    applied INTEGER,
+    suggested_action TEXT,
+    pattern_id TEXT,
+    created_at TEXT,
+    archived_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )
+`;
+export const DREAM_INSIGHTS_ARCHIVE_SCHEMA = `
+  ${DREAM_INSIGHTS_ARCHIVE_TABLE_SQL};
+  -- The sweep's read-back looks copies up by insight id.
+  CREATE INDEX IF NOT EXISTS idx_dream_insights_archive_id ON ${DREAM_INSIGHTS_ARCHIVE_TABLE}(id);
+`;
+export function applyMigration(db) {
+    db.exec(DREAM_INSIGHTS_ARCHIVE_SCHEMA);
+}
+export function isMigrationApplied(db) {
+    try {
+        const result = db.prepare(`SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name = ?`).get(DREAM_INSIGHTS_ARCHIVE_TABLE);
+        return result.count === 1;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=20261018_add_dream_insights_archive.js.map

package/dist/shared/git/git-analyzer.d.ts

@@ -57,6 +57,10 @@ export interface GitAnalyzerConfig {
     enableCache?: boolean;
     /** Cache TTL in milliseconds (default: 5 minutes) */
     cacheTtl?: number;
+    /** Deadline in milliseconds shared by the git calls of one analysis (default: 30 seconds) */
+    gitTimeoutMs?: number;
+    /** Deadline in milliseconds for all analyses of one file inside withFileDeadline() (default: 60 seconds) */
+    fileTimeoutMs?: number;
 }
 /**
  * Git Analyzer for defect prediction metrics
@@ -65,11 +69,27 @@ export declare class GitAnalyzer {
     private readonly config;
     private readonly cache;
     private isGitRepo;
+    /** After a rev-parse timeout, when to ask git again (until then: "timeout"). */
+    private repoRetryAt;
+    private readonly timedOutFiles;
+    /** Files inside withFileDeadline() and when their git time runs out. */
+    private readonly fileDeadlines;
     constructor(config?: GitAnalyzerConfig);
     /**
      * Check if current directory is a git repository
      */
     isGitRepository(): Promise<boolean>;
+    /**
+     * True when git timed out while analysing `filePath` since the last call, so
+     * the analysis returned its "git unavailable" default rather than a result.
+     */
+    consumeTimeout(filePath: string): boolean;
+    /**
+     * Run `work`, during which every analysis of `filePath` also stops at one
+     * shared `fileTimeoutMs` deadline. One file's analyses then wait for git at
+     * most that long together, rather than `gitTimeoutMs` each (#1115).
+     */
+    withFileDeadline<T>(filePath: string, work: () => Promise<T>): Promise<T>;
     /**
      * Get file change frequency (commits in last 90 days / 3)
      * Returns normalized value 0-1
@@ -98,6 +118,7 @@ export declare class GitAnalyzer {
      * Get files changed since a specific date
      * @param since - Date to check changes from (default: 24 hours ago)
      * @returns Array of changed file paths relative to repo root
+     * @throws GitTimeoutError when git does not answer within `gitTimeoutMs`
      */
     getChangedFiles(since?: Date): Promise<string[]>;
     /**
@@ -107,13 +128,41 @@ export declare class GitAnalyzer {
      * @throws Error when `commitHash` is option-shaped (starts with "-") or otherwise
      *   not a safe revision argument; git would otherwise parse it as an option
      *   (e.g. `--output=<path>` writes an arbitrary file). See issue #960.
+     * @throws GitTimeoutError when git does not answer within `gitTimeoutMs`
      */
     getCommitFiles(commitHash?: string): Promise<string[]>;
     /**
      * Get files with uncommitted changes (staged + unstaged)
      * @returns Array of modified file paths relative to repo root
+     * @throws GitTimeoutError when git does not answer within `gitTimeoutMs`
      */
     getUncommittedFiles(): Promise<string[]>;
+    /**
+     * Count commits whose message matches any bug keyword, in one `git log`
+     * (repeated --grep patterns are OR-ed). Keywords are sanitized arguments and
+     * never reach a shell.
+     */
+    private countBugFixCommits;
+    /**
+     * Run one file's analysis with every git call sharing one `gitTimeoutMs`
+     * deadline (#1115). When git is unavailable or times out, the analysis
+     * returns its default, which callers treat as "no git data", and a timeout
+     * is recorded for consumeTimeout(). A timeout never yields a measured 0.
+     */
+    private analyze;
+    /**
+     * Whether the repo root is a git work tree. A timeout is not an answer: it
+     * is remembered for `cacheTtl` so a hung git is not waited on for every
+     * file, and then git is asked again.
+     */
+    private repoState;
+    /**
+     * Git queries in the repo root that share a deadline of `gitTimeoutMs` from
+     * now, or `fileDeadline` when that comes first. Git runs asynchronously in its own process group, so a slow or hung
+     * git (a network filesystem, a credential prompt) neither blocks the MCP
+     * server's event loop nor outlives its deadline (#1115).
+     */
+    private query;
     /**
      * Get relative path from repo root
      */