agentic-qe 3.15.9 → 3.15.10

package/dist/learning/dream/spreading-activation.js

@@ -230,9 +230,10 @@ export class SpreadingActivation {
      * - Novel associations are discovered from unexpected co-activations
      *
      * @param durationMs - How long to dream in milliseconds
+     * @param signal - #1060: stops the dream early (engine closed, shutdown)
      * @returns Activation result from the dream cycle
      */
-    async dream(durationMs) {
+    async dream(durationMs, signal) {
         const startTime = Date.now();
         const allNovelAssociations = [];
         let totalIterations = 0;
@@ -251,7 +252,7 @@ export class SpreadingActivation {
         }
         // Dream loop with strict time enforcement
         const deadlineMs = startTime + durationMs;
-        while (Date.now() < deadlineMs) {
+        while (Date.now() < deadlineMs && !signal?.aborted) {
             // Randomly select a concept to activate
             const randomIndex = secureRandomInt(0, allConcepts.length);
             const randomNode = allConcepts[randomIndex];
@@ -277,10 +278,10 @@ export class SpreadingActivation {
                 }
             }
             // Check deadline again before sleeping
-            if (Date.now() >= deadlineMs)
+            if (Date.now() >= deadlineMs || signal?.aborted)
                 break;
             // Small delay to prevent CPU spike
-            await this.sleep(50 + secureRandom() * 50);
+            await this.sleep(50 + secureRandom() * 50, signal);
         }
         // Deduplicate and sort novel associations
         const uniqueAssociations = this.deduplicateAssociations(allNovelAssociations);
@@ -561,8 +562,16 @@ export class SpreadingActivation {
     /**
      * Helper to sleep for a duration
      */
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    sleep(ms, signal) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(done, ms);
+            function done() {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', done);
+                resolve();
+            }
+            signal?.addEventListener('abort', done, { once: true });
+        });
     }
 }
 export default SpreadingActivation;

package/dist/learning/experience-capture.d.ts

@@ -71,6 +71,11 @@ export interface TaskExperience {
     reward?: number;
     /** Test outcome category (if applicable) */
     testOutcome?: TestOutcome;
+    /**
+     * #1129: what `success` was read from (e.g. test-results). Absent when the
+     * caller only knows the task completed; such usage is not a measured outcome.
+     */
+    outcomeBasis?: string;
     /** Feedback provided */
     feedback?: string;
     /** Extracted patterns (if any) */
@@ -209,6 +214,8 @@ export declare class ExperienceCaptureService {
         quality?: number;
         feedback?: string;
         testOutcome?: TestOutcome;
+        /** #1129: set when `success` was read from the result, not from completion. */
+        outcomeBasis?: string;
     }): Promise<Result<TaskExperience>>;
     /**
      * Get an active experience
@@ -295,6 +302,8 @@ export declare class ExperienceCaptureService {
     /**
      * Convert experience to pattern options
      */
+    /** #1129: tag the usage row so readers can tell a measured outcome from completion. */
+    private usageOutcomeTag;
     private experienceToPatternOptions;
     /**
      * Detect pattern type from task description

package/dist/learning/experience-capture.js

@@ -19,6 +19,7 @@ import { LoggerFactory } from '../logging/index.js';
 import { getRuVectorFeatureFlags } from '../integrations/ruvector/feature-flags.js';
 const logger = LoggerFactory.create('experience-capture');
 import { PROMOTION_THRESHOLD } from './qe-patterns.js';
+import { usageOutcomeMetrics } from './usage-outcome.js';
 /**
  * Reward values for each test outcome.
  * Based on GRPO (Group Relative Policy Optimization) binary reward model.
@@ -181,6 +182,8 @@ export class ExperienceCaptureService {
         experience.durationMs = now - experience.startedAt;
         experience.success = outcome.success;
         experience.feedback = outcome.feedback;
+        if (outcome.outcomeBasis)
+            experience.outcomeBasis = outcome.outcomeBasis;
         // Calculate quality from steps if not provided
         if (outcome.quality !== undefined) {
             experience.quality = outcome.quality;
@@ -250,9 +253,11 @@ export class ExperienceCaptureService {
         // Extract patterns: require positive reward (or no reward signal) AND quality threshold
         // Zero or negative reward blocks extraction — only learn from genuinely positive outcomes
         const rewardAllowsExtraction = experience.reward === undefined || experience.reward > 0;
-        if (experience.success &&
+        // #1129: a measured outcome is recorded whether it succeeded or failed.
+        // Recording only successes made the usage success rate 100% by selection.
+        if (experience.outcomeBasis !== undefined || (experience.success &&
             experience.quality >= this.config.minQualityForPatternExtraction &&
-            rewardAllowsExtraction) {
+            rewardAllowsExtraction)) {
             const extractionResult = await this.extractPattern(experience);
             if (extractionResult.newPattern || extractionResult.reinforced) {
                 experience.patterns = [extractionResult.patternId];
@@ -391,11 +396,13 @@ export class ExperienceCaptureService {
                 && origin.patternType === this.detectPatternType(experience.task)
                 && existing.pattern.patternType === origin.patternType
                 && (!experience.domain || existing.pattern.qeDomain === experience.domain)) {
-                const usageResult = await this.patternStore.recordUsage(existing.pattern.id, experience.success);
+                const usageResult = await this.patternStore.recordUsage(existing.pattern.id, experience.success, this.usageOutcomeTag(experience));
                 // Check if pattern should be promoted (short-term → long-term)
                 const pattern = await this.patternStore.get(existing.pattern.id);
                 let promoted = false;
+                // A failed use is now recorded too (#1129); it never promotes.
                 if (pattern &&
+                    experience.success &&
                     pattern.tier === 'short-term' &&
                     pattern.usageCount >= this.config.promotionThreshold) {
                     // Actually promote the pattern
@@ -420,7 +427,7 @@ export class ExperienceCaptureService {
         if (createResult.success) {
             this.stats.patternsExtracted++;
             // Record the initial usage (the experience that created this pattern)
-            await this.patternStore.recordUsage(createResult.value.id, experience.success);
+            await this.patternStore.recordUsage(createResult.value.id, experience.success, this.usageOutcomeTag(experience));
             return {
                 newPattern: true,
                 patternId: createResult.value.id,
@@ -583,6 +590,13 @@ export class ExperienceCaptureService {
     /**
      * Convert experience to pattern options
      */
+    /** #1129: tag the usage row so readers can tell a measured outcome from completion. */
+    usageOutcomeTag(experience) {
+        const runId = typeof experience.metadata?.runId === 'string' ? experience.metadata.runId : undefined;
+        return experience.outcomeBasis !== undefined
+            ? usageOutcomeMetrics({ measured: true, success: experience.success, basis: experience.outcomeBasis }, runId)
+            : usageOutcomeMetrics({ measured: false, success: null, basis: 'task-completed' }, runId);
+    }
     experienceToPatternOptions(experience) {
         // Detect pattern type from task
         const patternType = this.detectPatternType(experience.task);

package/dist/learning/qe-reasoning-bank-types.d.ts

@@ -107,6 +107,12 @@ export interface LearningOutcome {
         testsFailed?: number;
         coverageImprovement?: number;
         executionTimeMs?: number;
+        /** #1129: whether `success` was read from the result or only from completion. */
+        outcome?: 'measured' | 'unmeasured';
+        /** #1129: what a measured verdict was read from (e.g. test-results). */
+        outcomeBasis?: string;
+        /** #1129: the run this use belongs to; one run may use several patterns. */
+        runId?: string;
     };
     /** Feedback from the agent or user */
     feedback?: string;
@@ -183,8 +189,17 @@ export interface QEReasoningBankStats {
     avgRoutingConfidence: number;
     /** Learning outcomes recorded */
     learningOutcomes: number;
-    /** Pattern success rate */
-    patternSuccessRate: number;
+    /** #1129: measured runs (success read from the result, e.g. test counts). */
+    measuredOutcomes?: number;
+    /** #1129: usage rows without a measured outcome; left out of the rate. */
+    unmeasuredOutcomes?: number;
+    /**
+     * Share of measured runs that succeeded; null when none is measured
+     * (#1129) instead of a rate built from completed calls.
+     */
+    patternSuccessRate: number | null;
+    /** #1129: set when no measured outcome exists to compute patternSuccessRate. */
+    evidenceStatus?: 'insufficient-evidence';
     /** Pattern store stats */
     patternStoreStats: import('./pattern-store.js').PatternStoreStats;
     /** ADR-061: Asymmetric learning metrics (optional, available in RealQEReasoningBank) */

package/dist/learning/qe-reasoning-bank.js

@@ -33,6 +33,7 @@ import { resolveTopologyCriticalFromSharedMincut } from './routing-topology-gate
 import { getUnifiedMemory } from '../kernel/unified-memory.js';
 import { resizeEmbedding, hashEmbedding } from './embedding-utils.js';
 import { maybeEnhanceRoutingWithPatterns } from './pattern-routing-guidance.js';
+import { usageOutcomeOf } from './usage-outcome.js';
 import { checkPatternPromotionWithCoherence, promotePattern as promotePatternFn, seedCrossDomainPatterns as seedCrossDomainPatternsFn, } from './pattern-promotion.js';
 // ============================================================================
 // QEReasoningBank Implementation
@@ -97,6 +98,7 @@ export class QEReasoningBank {
         routingRequests: 0,
         totalRoutingConfidence: 0,
         learningOutcomes: 0,
+        measuredOutcomes: 0,
         successfulOutcomes: 0,
     };
     constructor(memory, eventBus, config = {}, coherenceService) {
@@ -431,8 +433,12 @@ export class QEReasoningBank {
         const result = await this.patternStore.recordUsage(outcome.patternId, outcome.success, outcome.metrics, outcome.feedback);
         if (result.success) {
             this.stats.learningOutcomes++;
-            if (outcome.success) {
-                this.stats.successfulOutcomes++;
+            // #1129: only a measured outcome counts toward the success rate.
+            const measured = usageOutcomeOf(outcome.metrics) === 'measured';
+            if (measured) {
+                this.stats.measuredOutcomes++;
+                if (outcome.success)
+                    this.stats.successfulOutcomes++;
             }
             // ADR-070: Record pattern update in witness chain
             getWitnessChain().then(wc => wc.append('PATTERN_UPDATE', { patternId: outcome.patternId, success: outcome.success }, 'reasoning-bank')).catch((e) => { logger.warn('Witness chain PATTERN_UPDATE failed', { error: toErrorMessage(e) }); });
@@ -721,9 +727,10 @@ export class QEReasoningBank {
             ? this.stats.totalRoutingConfidence / this.stats.routingRequests
             : 0;
         let learningOutcomes = this.stats.learningOutcomes;
-        let patternSuccessRate = this.stats.learningOutcomes > 0
-            ? this.stats.successfulOutcomes / this.stats.learningOutcomes
-            : 0;
+        // In process each recorded outcome is its own run; the DB groups by runId.
+        let measuredOutcomes = this.stats.measuredOutcomes;
+        let unmeasuredOutcomes = this.stats.learningOutcomes - this.stats.measuredOutcomes;
+        let successfulOutcomes = this.stats.successfulOutcomes;
         try {
             const agg = this.getSqliteStore().getAggregateOutcomeStats();
             if (agg.routingRequests > routingRequests) {
@@ -732,24 +739,28 @@ export class QEReasoningBank {
             }
             if (agg.learningOutcomes > learningOutcomes) {
                 learningOutcomes = agg.learningOutcomes;
-                // Prefer per-usage success rate (closer to recordOutcome semantics);
-                // fall back to qe_patterns.success_rate aggregate when no usage rows.
-                patternSuccessRate =
-                    agg.learningOutcomes > 0
-                        ? agg.successfulOutcomes / agg.learningOutcomes
-                        : agg.avgPatternSuccessRate;
+                measuredOutcomes = agg.measuredOutcomes;
+                unmeasuredOutcomes = agg.unmeasuredOutcomes;
+                successfulOutcomes = agg.successfulOutcomes;
             }
         }
         catch {
             // best-effort — never let stats reporting crash the host
         }
+        // #1129: the rate is over measured outcomes only. A usage row that only
+        // records a completed call says nothing about whether the result was
+        // good, so with none measured there is no rate to report.
+        const patternSuccessRate = measuredOutcomes > 0 ? successfulOutcomes / measuredOutcomes : null;
         return {
             totalPatterns: patternStoreStats.totalPatterns,
             byDomain,
             routingRequests,
             avgRoutingConfidence,
             learningOutcomes,
+            measuredOutcomes,
+            unmeasuredOutcomes,
             patternSuccessRate,
+            ...(patternSuccessRate === null ? { evidenceStatus: 'insufficient-evidence' } : {}),
             patternStoreStats,
         };
     }

package/dist/learning/sqlite-persistence.d.ts

@@ -185,12 +185,18 @@ export declare class SQLitePatternStore {
      * routing_outcomes and qe_pattern_usage live in the same unified memory.db
      * as qe_patterns. avgConfidence/avgSuccessRate return 0 when the source
      * tables are empty rather than NaN.
+     *
+     * #1129: measuredOutcomes and successfulOutcomes count measured runs (rows
+     * tagged outcome 'measured', grouped by runId); unmeasuredOutcomes counts
+     * every other usage row. learningOutcomes stays the total row count.
      */
     getAggregateOutcomeStats(): {
         routingRequests: number;
         avgRoutingConfidence: number;
         successfulRoutings: number;
         learningOutcomes: number;
+        measuredOutcomes: number;
+        unmeasuredOutcomes: number;
         successfulOutcomes: number;
         avgPatternSuccessRate: number;
     };

package/dist/learning/sqlite-persistence.js

@@ -21,6 +21,7 @@ import { ensurePatternFtsInSync } from '../kernel/pattern-fts-self-heal.js';
 import { computeBatchEmbeddings, getEmbeddingDimension, isUsingEndpoint, getActiveEmbeddingSpaceIdentity, } from './real-embeddings.js';
 import { EMBEDDING_SPACE_CANARY, inspectEmbeddingSpaceRows, } from './embedding-space.js';
 import { recordPatternUsage } from './pattern-usage-recorder.js';
+import { MEASURED_USAGE_SQL, USAGE_RUN_SQL } from './usage-outcome.js';
 export const DEFAULT_SQLITE_CONFIG = {
     // LEGACY: Ignored when useUnified=true (the default). All data goes to memory.db
     dbPath: '.agentic-qe/memory.db',
@@ -718,6 +719,10 @@ export class SQLitePatternStore {
      * routing_outcomes and qe_pattern_usage live in the same unified memory.db
      * as qe_patterns. avgConfidence/avgSuccessRate return 0 when the source
      * tables are empty rather than NaN.
+     *
+     * #1129: measuredOutcomes and successfulOutcomes count measured runs (rows
+     * tagged outcome 'measured', grouped by runId); unmeasuredOutcomes counts
+     * every other usage row. learningOutcomes stays the total row count.
      */
     getAggregateOutcomeStats() {
         const empty = {
@@ -725,6 +730,8 @@ export class SQLitePatternStore {
             avgRoutingConfidence: 0,
             successfulRoutings: 0,
             learningOutcomes: 0,
+            measuredOutcomes: 0,
+            unmeasuredOutcomes: 0,
             successfulOutcomes: 0,
             avgPatternSuccessRate: 0,
         };
@@ -751,8 +758,13 @@ export class SQLitePatternStore {
         const usage = safeGet(`
       SELECT
         COUNT(*) AS total,
-        COALESCE(SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END), 0) AS succ
-      FROM qe_pattern_usage
+        COALESCE(SUM(measured), 0) AS measuredRows,
+        COUNT(DISTINCT CASE WHEN measured = 1 THEN run END) AS measured,
+        COUNT(DISTINCT CASE WHEN measured = 1 AND success = 1 THEN run END) AS succ
+      FROM (
+        SELECT success, ${MEASURED_USAGE_SQL} AS measured, ${USAGE_RUN_SQL} AS run
+        FROM qe_pattern_usage
+      )
     `);
         const patternAvg = safeGet(`
       SELECT AVG(success_rate) AS avg_sr
@@ -764,6 +776,8 @@ export class SQLitePatternStore {
             avgRoutingConfidence: routing?.avg_q ?? 0,
             successfulRoutings: routing?.succ ?? 0,
             learningOutcomes: usage?.total ?? 0,
+            measuredOutcomes: usage?.measured ?? 0,
+            unmeasuredOutcomes: (usage?.total ?? 0) - (usage?.measuredRows ?? 0),
             successfulOutcomes: usage?.succ ?? 0,
             avgPatternSuccessRate: patternAvg?.avg_sr ?? 0,
         };

package/dist/learning/usage-outcome.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Agentic QE v3 - Measured outcomes for pattern usage (#1129)
+ *
+ * `qe_pattern_usage.success` used to mean "the call completed": MCP tool runs
+ * were captured with a fixed `success: true`, hooks pass a hardcoded
+ * `--success`, and session consolidation writes only aggregates whose success
+ * rate already passed a threshold. The aggregate "Pattern Success Rate" was
+ * 100% by construction.
+ *
+ * A usage row counts as a measured outcome only when it says so:
+ * `metrics_json.outcome = 'measured'`, written when success was read from the
+ * result. Today that is a test run: every test passed, or some failed.
+ * Every other row, whatever its age or writer, is unmeasured (tag and exclude,
+ * the #1109 decision): it is kept and counted as a use, never rewritten, and
+ * never part of the rate.
+ *
+ * The rate is per run, not per row: one tool run writes a row for each
+ * pattern involved (the captured experience's pattern plus every routing
+ * hint), all with the same verdict, and they share `metrics_json.runId`.
+ */
+export type UsageOutcome = 'measured' | 'unmeasured';
+/** The outcome of one tool run, as far as its result shows it. */
+export interface ToolOutcome {
+    /** True when `success` was read from the result, not from completion. */
+    readonly measured: boolean;
+    /** For a measured outcome, whether it was good; otherwise null. */
+    readonly success: boolean | null;
+    /** What the verdict was read from, e.g. `test-results`. */
+    readonly basis: string;
+}
+/**
+ * Read the outcome of a completed tool run from its result.
+ * Tools without an outcome measure here are `unmeasured`: completing is not
+ * evidence that the result was good.
+ */
+export declare function measureToolOutcome(taskType: string, data: unknown): ToolOutcome;
+/** Metrics fields that tag a usage row with its outcome provenance and run. */
+export declare function usageOutcomeMetrics(outcome: ToolOutcome, runId?: string): {
+    outcome: UsageOutcome;
+    outcomeBasis: string;
+    runId?: string;
+};
+/** Classify one qe_pattern_usage row (TypeScript twin of MEASURED_USAGE_SQL). */
+export declare function usageOutcomeOf(metrics: Record<string, unknown> | null | undefined): UsageOutcome;
+/**
+ * SQL expression over qe_pattern_usage: 1 for a measured row, 0 otherwise.
+ * Mirrors usageOutcomeOf; json_valid keeps a malformed row from failing the query.
+ */
+export declare const MEASURED_USAGE_SQL = "(CASE WHEN json_valid(metrics_json) AND json_extract(metrics_json, '$.outcome') = 'measured' THEN 1 ELSE 0 END)";
+/** SQL expression: the run a usage row belongs to (a row without runId is its own run). */
+export declare const USAGE_RUN_SQL = "COALESCE(CASE WHEN json_valid(metrics_json) THEN json_extract(metrics_json, '$.runId') END, 'row:' || id)";
+/** Fields of the reasoning-bank stats that describe usage outcomes. */
+interface OutcomeStats {
+    learningOutcomes: number;
+    measuredOutcomes?: number;
+    patternSuccessRate: number | null;
+}
+/**
+ * e.g. "9 (4 measured runs, 0 unmeasured)". A run can write several usage
+ * rows (one per pattern involved), so measured runs can be fewer than rows.
+ */
+export declare function formatLearningOutcomes(stats: OutcomeStats & {
+    unmeasuredOutcomes?: number;
+}): string;
+/** The rate as a percentage, or why there is none (#1129). */
+export declare function formatPatternSuccessRate(stats: OutcomeStats): string;
+export {};
+//# sourceMappingURL=usage-outcome.d.ts.map

package/dist/learning/usage-outcome.js

@@ -0,0 +1,84 @@
+/**
+ * Agentic QE v3 - Measured outcomes for pattern usage (#1129)
+ *
+ * `qe_pattern_usage.success` used to mean "the call completed": MCP tool runs
+ * were captured with a fixed `success: true`, hooks pass a hardcoded
+ * `--success`, and session consolidation writes only aggregates whose success
+ * rate already passed a threshold. The aggregate "Pattern Success Rate" was
+ * 100% by construction.
+ *
+ * A usage row counts as a measured outcome only when it says so:
+ * `metrics_json.outcome = 'measured'`, written when success was read from the
+ * result. Today that is a test run: every test passed, or some failed.
+ * Every other row, whatever its age or writer, is unmeasured (tag and exclude,
+ * the #1109 decision): it is kept and counted as a use, never rewritten, and
+ * never part of the rate.
+ *
+ * The rate is per run, not per row: one tool run writes a row for each
+ * pattern involved (the captured experience's pattern plus every routing
+ * hint), all with the same verdict, and they share `metrics_json.runId`.
+ */
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : null;
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * Read the outcome of a completed tool run from its result.
+ * Tools without an outcome measure here are `unmeasured`: completing is not
+ * evidence that the result was good.
+ */
+export function measureToolOutcome(taskType, data) {
+    const record = asRecord(data);
+    if (taskType === 'execute-tests') {
+        const total = finiteNumber(record?.total);
+        const failed = finiteNumber(record?.failed);
+        if (total !== null && total > 0 && failed !== null) {
+            return { measured: true, success: failed === 0, basis: 'test-results' };
+        }
+        return { measured: false, success: null, basis: 'no-test-results' };
+    }
+    // index-code is not measured (#1142 review): it fails both for the caller's
+    // input (a missing, empty or outside target) and for indexer errors, and the
+    // result does not tell them apart. Counting only the successful indexes
+    // would make its rate 100% by selection again.
+    return { measured: false, success: null, basis: 'tool-completed' };
+}
+/** Metrics fields that tag a usage row with its outcome provenance and run. */
+export function usageOutcomeMetrics(outcome, runId) {
+    return {
+        outcome: outcome.measured ? 'measured' : 'unmeasured',
+        outcomeBasis: outcome.basis,
+        ...(runId ? { runId } : {}),
+    };
+}
+/** Classify one qe_pattern_usage row (TypeScript twin of MEASURED_USAGE_SQL). */
+export function usageOutcomeOf(metrics) {
+    return metrics?.outcome === 'measured' ? 'measured' : 'unmeasured';
+}
+/**
+ * SQL expression over qe_pattern_usage: 1 for a measured row, 0 otherwise.
+ * Mirrors usageOutcomeOf; json_valid keeps a malformed row from failing the query.
+ */
+export const MEASURED_USAGE_SQL = `(CASE WHEN json_valid(metrics_json) AND json_extract(metrics_json, '$.outcome') = 'measured' THEN 1 ELSE 0 END)`;
+/** SQL expression: the run a usage row belongs to (a row without runId is its own run). */
+export const USAGE_RUN_SQL = `COALESCE(CASE WHEN json_valid(metrics_json) THEN json_extract(metrics_json, '$.runId') END, 'row:' || id)`;
+/**
+ * e.g. "9 (4 measured runs, 0 unmeasured)". A run can write several usage
+ * rows (one per pattern involved), so measured runs can be fewer than rows.
+ */
+export function formatLearningOutcomes(stats) {
+    if (stats.learningOutcomes === 0)
+        return '0';
+    const measured = stats.measuredOutcomes ?? 0;
+    const unmeasured = stats.unmeasuredOutcomes ?? stats.learningOutcomes;
+    return `${stats.learningOutcomes} (${measured} measured runs, ${unmeasured} unmeasured)`;
+}
+/** The rate as a percentage, or why there is none (#1129). */
+export function formatPatternSuccessRate(stats) {
+    return stats.patternSuccessRate === null
+        ? 'insufficient evidence (no measured outcomes)'
+        : `${(stats.patternSuccessRate * 100).toFixed(1)}% of ${stats.measuredOutcomes ?? 0} measured runs`;
+}
+//# sourceMappingURL=usage-outcome.js.map

package/dist/mcp/background-workers.d.ts

@@ -10,6 +10,18 @@
  * stderr writer so stdout stays reserved for JSON-RPC.
  */
 import { type WorkerEnv } from '../workers/worker-env.js';
-export type BackgroundWorkersOutcome = 'disabled' | 'started' | 'failed';
+/**
+ * #1116: `starting` while the worker daemon's first runs continue in the
+ * background; `startBackgroundWorkers` never reports `started` before they
+ * have finished. The settled state is in `getBackgroundWorkersState()`.
+ */
+export type BackgroundWorkersOutcome = 'disabled' | 'starting' | 'failed';
+export interface BackgroundWorkersState {
+    state: 'not-requested' | 'disabled' | 'starting' | 'started' | 'failed';
+    /** Why the start failed, when `state` is `failed`. */
+    error?: string;
+}
+/** Where the worker daemon's start stands now, including a background failure. */
+export declare function getBackgroundWorkersState(): BackgroundWorkersState;
 export declare function startBackgroundWorkers(log: (message: string) => void, env?: WorkerEnv): Promise<BackgroundWorkersOutcome>;
 //# sourceMappingURL=background-workers.d.ts.map

package/dist/mcp/background-workers.js

@@ -10,10 +10,16 @@
  * stderr writer so stdout stays reserved for JSON-RPC.
  */
 import { isWorkersEnabled } from '../workers/worker-env.js';
+let workersState = { state: 'not-requested' };
+/** Where the worker daemon's start stands now, including a background failure. */
+export function getBackgroundWorkersState() {
+    return { ...workersState };
+}
 export async function startBackgroundWorkers(log, env = process.env) {
     if (!isWorkersEnabled(env)) {
         log(`[MCP] Background workers disabled (AQE_WORKERS_ENABLED=${env.AQE_WORKERS_ENABLED}); ` +
             'worker daemon and quality daemon not started\n');
+        workersState = { state: 'disabled' };
         return 'disabled';
     }
     // In database-free mode the workers run against the in-memory unified
@@ -31,11 +37,18 @@ export async function startBackgroundWorkers(log, env = process.env) {
         // #1066: start() runs every worker's first tick one after another, which
         // can take minutes. Let it finish in the background so the QualityDaemon
         // (and the HTTP server after us) do not wait for it.
-        void daemon.start().catch((startError) => {
+        // #1116: report `starting` now and the real outcome when it settles, so a
+        // start that fails in the background is never reported as started.
+        workersState = { state: 'starting' };
+        void daemon.start().then(() => {
+            workersState = { state: 'started' };
+            log('[MCP] Background workers started (first runs complete)\n');
+        }, (startError) => {
+            workersState = { state: 'failed', error: String(startError) };
             log(`[MCP] WARNING: Background workers failed to start: ${startError}\n`);
         });
         const status = daemon.getStatus();
-        log(`[MCP] Background workers started (${status.workerManager.totalWorkers} workers; ` +
+        log(`[MCP] Background workers starting (${status.workerManager.totalWorkers} workers; ` +
             'first runs continue in the background)\n');
         // IMP-10: Start QualityDaemon with persistent memory (Finding 1 & 2 resolution)
         try {
@@ -66,9 +79,10 @@ export async function startBackgroundWorkers(log, env = process.env) {
             log(`[MCP] WARNING: Quality daemon failed to start: ${qdError}\n`);
             // Non-fatal — MCP continues without quality daemon
         }
-        return 'started';
+        return 'starting';
     }
     catch (daemonError) {
+        workersState = { state: 'failed', error: String(daemonError) };
         log(`[MCP] WARNING: Background workers failed to start: ${daemonError}\n`);
         // Non-fatal — MCP server continues without background workers
         return 'failed';