agentic-qe 3.15.11 → 3.15.12

package/dist/coordination/handlers/handler-utils.d.ts

@@ -74,6 +74,11 @@ export interface IstanbulFileCoverage {
  * Load coverage data from common coverage file formats
  */
 export declare function loadCoverageData(targetPath: string): Promise<CoverageData | null>;
+/** `loadCoverageData` plus the path of the report it read (#1154: staleness needs it). */
+export declare function loadCoverageReport(targetPath: string): Promise<{
+    data: CoverageData;
+    path: string;
+} | null>;
 /**
  * Per-line hit counts of one istanbul file entry, computed the way istanbul's
  * own `FileCoverage#getLineCoverage` (and therefore coverage-summary.json

package/dist/coordination/handlers/handler-utils.js

@@ -16,6 +16,10 @@ import { safeJsonParse } from '../../shared/safe-json.js';
  * Load coverage data from common coverage file formats
  */
 export async function loadCoverageData(targetPath) {
+    return (await loadCoverageReport(targetPath))?.data ?? null;
+}
+/** `loadCoverageData` plus the path of the report it read (#1154: staleness needs it). */
+export async function loadCoverageReport(targetPath) {
     // Try various coverage file locations (JS, Python, Java, etc.)
     const coverageLocations = [
         // JavaScript/TypeScript (Istanbul/nyc/vitest)
@@ -36,16 +40,16 @@ export async function loadCoverageData(targetPath) {
             // #1161: a report linked out of the project, or to a device, is not read.
             const content = await readConfinedText(coveragePath, { outsideRoot: 'allow' });
             if (coveragePath.endsWith('coverage-summary.json')) {
-                return parseCoverageSummaryJson(content);
+                return { data: parseCoverageSummaryJson(content), path: coveragePath };
             }
             else if (coveragePath.endsWith('.json')) {
-                return parseCoverageJson(content);
+                return { data: parseCoverageJson(content), path: coveragePath };
             }
             else if (coveragePath.endsWith('.info')) {
-                return parseLcovInfo(content);
+                return { data: parseLcovInfo(content), path: coveragePath };
             }
             else if (coveragePath.endsWith('.xml')) {
-                return parseCoberturaXml(content);
+                return { data: parseCoberturaXml(content), path: coveragePath };
             }
         }
         catch {

package/dist/domains/code-intelligence/services/metric-collector/listing-process-owner.js

@@ -32,7 +32,10 @@ function interrupted(signal) {
     removeHandlers();
     // Restore signal termination (including its exit status) instead of swallowing
     // Ctrl-C or converting a requested shutdown into a successful metrics result.
-    process.kill(process.pid, signal);
+    // An embedding host with its own listener already received this signal, so
+    // re-raising would deliver it twice; the host decides how to shut down (#992).
+    if (process.listenerCount(signal) === 0)
+        process.kill(process.pid, signal);
 }
 const signalHandlers = {
     SIGINT: () => interrupted('SIGINT'),

package/dist/domains/code-intelligence/services/semantic-analyzer.d.ts

@@ -134,6 +134,14 @@ export declare class SemanticAnalyzerService implements ISemanticAnalyzerService
     private findHighlights;
     private findSemanticHighlights;
     private fileToKey;
+    /**
+     * Content identity for the analysis and embedding caches.
+     *
+     * This keys cache entries, so it has to separate any two distinct inputs.
+     * A 31-multiplier 32-bit hash does not: for any shared prefix and suffix,
+     * "Aa" and "BB" collide, so two different functions would share one entry
+     * and the second caller would receive the first one's result.
+     */
     private hashCode;
     private cacheEmbedding;
     private cacheAnalysis;

package/dist/domains/code-intelligence/services/semantic-analyzer.js

@@ -2,6 +2,7 @@
  * Agentic QE v3 - Semantic Analyzer Service
  * Semantic code analysis using vector embeddings and HNSW search
  */
+import { createHash } from 'node:crypto';
 import { ok, err } from '../../../shared/types/index.js';
 import { NomicEmbedder, EMBEDDING_CONFIG, } from '../../../shared/embeddings/index.js';
 import { toError } from '../../../shared/error-utils.js';
@@ -635,14 +636,16 @@ export class SemanticAnalyzerService {
     fileToKey(file) {
         return file.replace(/[/\\]/g, ':').replace(/\./g, '_');
     }
+    /**
+     * Content identity for the analysis and embedding caches.
+     *
+     * This keys cache entries, so it has to separate any two distinct inputs.
+     * A 31-multiplier 32-bit hash does not: for any shared prefix and suffix,
+     * "Aa" and "BB" collide, so two different functions would share one entry
+     * and the second caller would receive the first one's result.
+     */
     hashCode(str) {
-        let hash = 0;
-        for (let i = 0; i < str.length; i++) {
-            const char = str.charCodeAt(i);
-            hash = (hash << 5) - hash + char;
-            hash = hash & hash;
-        }
-        return hash.toString(16);
+        return createHash('sha256').update(str, 'utf8').digest('hex');
     }
     cacheEmbedding(key, embedding) {
         if (this.embeddingCache.size >= this.config.cacheSize) {

package/dist/init/phases/10-workers.js

@@ -173,6 +173,26 @@ if (workersSetting !== undefined && ['false', '0', 'off', 'no'].includes(workers
   process.exit(0);
 }
 
+// #1207: keep daemon.log bounded. The server truncates it on its heartbeat once
+// it passes AQE_DAEMON_LOG_MAX_SIZE (default 5M, 0 or off disables); a log left
+// over that size by an earlier run is moved to daemon.log.1 here, before
+// anything writes to it. rename() replaces daemon.log.1 and never follows it.
+function logMaxBytes() {
+  const text = String(process.env.AQE_DAEMON_LOG_MAX_SIZE || '').trim().toLowerCase();
+  if (['0', 'off', 'false', 'no', 'none', 'disable', 'disabled'].includes(text)) return 0;
+  const m = /^(\\d+)\\s*([kmg]?)b?$/.exec(text);
+  const bytes = m ? Number(m[1]) * { '': 1, k: 1024, m: 1048576, g: 1073741824 }[m[2]] : NaN;
+  return Number.isSafeInteger(bytes) && bytes >= 1024 ? bytes : 5 * 1048576;
+}
+function rotateLogAtStart(file) {
+  const max = logMaxBytes();
+  try {
+    const s = fs.lstatSync(file);
+    if (max > 0 && s.isFile() && s.size > max) fs.renameSync(file, file + '.1');
+  } catch {}
+}
+rotateLogAtStart(logFile);
+
 const ts = new Date().toISOString();
 appendFileSync(logFile, '[' + ts + '] Starting AQE v3 Worker Daemon...\\n');
 
@@ -228,10 +248,28 @@ if (binCandidate && binCandidate.endsWith('bundle.js')) {
 appendFileSync(logFile, '[' + ts + '] Using: ' + mcpCmd + ' ' + mcpArgs.join(' ') + '\\n');
 
 // #1066: keep a user's AQE_WORKERS_ENABLED (for example false) instead of forcing it on.
-const env = { ...process.env, AQE_STORAGE_PATH: '.agentic-qe', AQE_LEARNING_ENABLED: 'true', AQE_WORKERS_ENABLED: workersSetting ?? 'true', AQE_HTTP_PORT: '0' };
-const child = spawn(mcpCmd, mcpArgs, { cwd: projectRoot, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
-child.stdout.on('data', d => appendFileSync(logFile, d));
-child.stderr.on('data', d => appendFileSync(logFile, d));
+// #1158: AQE_MCP_DAEMON=1 is daemon mode. The server has no stdin here, so
+// without it the stdin-EOF guard (#513) shut it down right after starting;
+// in daemon mode it stops only on SIGTERM/SIGINT (stop-daemon.cjs).
+const env = { ...process.env, AQE_STORAGE_PATH: '.agentic-qe', AQE_LEARNING_ENABLED: 'true', AQE_WORKERS_ENABLED: workersSetting ?? 'true', AQE_HTTP_PORT: '0', AQE_MCP_DAEMON: '1' };
+// #1158: the server writes daemon.log itself, through a descriptor opened
+// here with the same symlink rules as appendFileSync. Piping its output
+// through this script kept the script from exiting while the daemon ran, and
+// once the script was gone nothing was logged any more.
+function openLogFd(file) {
+  if (!isRegularOrAbsent(file)) return 'ignore';
+  const c = fs.constants;
+  try { return fs.openSync(file, c.O_APPEND | c.O_CREAT | c.O_WRONLY | (c.O_NOFOLLOW || 0), 0o644); } catch { return 'ignore'; }
+}
+const logFd = openLogFd(logFile);
+// #1207: name the file behind the server's stdout/stderr so it can rotate it.
+if (typeof logFd === 'number') env.AQE_MCP_DAEMON_LOG = logFile; else delete env.AQE_MCP_DAEMON_LOG;
+let child;
+try {
+  child = spawn(mcpCmd, mcpArgs, { cwd: projectRoot, env, detached: true, stdio: ['ignore', logFd, logFd] });
+} finally {
+  if (typeof logFd === 'number') { try { fs.closeSync(logFd); } catch {} }
+}
 let exited = null;
 child.on('exit', (code, signal) => { exited = { code, signal }; });
 // #1116: a command that cannot be started (no npx on PATH: spawn ENOENT) emits

package/dist/integrations/agentic-flow/reasoning-bank/experience-replay.d.ts

@@ -71,6 +71,15 @@ export interface ExperienceGuidance {
     /** Estimated token savings */
     readonly estimatedTokenSavings: number;
 }
+/**
+ * #1204: whether similar-experience guidance can use vectors. 'unavailable'
+ * means the embedder failed (or there is none): experiences are stored
+ * without vectors and getGuidance returns no guidance.
+ */
+export interface ExperienceGuidanceStatus {
+    mode: 'vector' | 'unavailable';
+    reason?: string;
+}
 /**
  * Configuration for ExperienceReplay
  */
@@ -89,6 +98,8 @@ export interface ExperienceReplayConfig {
     autoPrune: boolean;
     /** Prune threshold (quality below this is removed) */
     pruneThreshold: number;
+    /** #1204: after the embedder fails, wait this long before retrying it (default 60 s). */
+    embedderRetryIntervalMs?: number;
 }
 /**
  * ExperienceReplay stores and retrieves successful experiences for learning.
@@ -113,7 +124,13 @@ export declare class ExperienceReplay {
     private prepared;
     private initialized;
     private initializationPromise;
-    private embedderUnavailableLogged;
+    /**
+     * #1204: whether the embedder works; retried in the background after a
+     * failure, as the pattern banks do (#1187).
+     */
+    private readonly embedderRecovery;
+    /** Whether an embedding succeeded, to label later failures as runtime ones. */
+    private embedderWorked;
     private hnswIndex;
     private idToExperienceId;
     private experienceIdToHnswId;
@@ -155,8 +172,13 @@ export declare class ExperienceReplay {
      * #1022: embed text, or return null when no embedding runtime is available.
      * The experience is then stored without a vector (backfilled at a later
      * start that has an embedder) and similarity search finds no matches.
+     * #1204: a failure is reported by getEmbedderStatus(), labelled as a
+     * runtime failure when the embedder had worked, and warned about once per
+     * outage. The embedder is retried in the background after the interval.
      */
     private embedOrNull;
+    /** #1204: whether similar-experience guidance can use vectors, and if not why. */
+    getEmbedderStatus(): ExperienceGuidanceStatus;
     /**
      * Get guidance for a new task based on similar experiences
      *

package/dist/integrations/agentic-flow/reasoning-bank/experience-replay.js

@@ -14,7 +14,8 @@
  */
 import { v4 as uuidv4 } from 'uuid';
 import { getUnifiedMemory } from '../../../kernel/unified-memory.js';
-import { computeRealEmbedding, } from '../../../learning/real-embeddings.js';
+import { computeRealEmbedding, cosineSimilarity, } from '../../../learning/real-embeddings.js';
+import { EmbedderRecovery, probeEmbedder } from '../../../learning/embedder-recovery.js';
 import { CircularBuffer } from '../../../shared/utils/circular-buffer.js';
 import { HNSWEmbeddingIndex } from '../../embeddings/index/HNSWIndex.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
@@ -60,7 +61,13 @@ export class ExperienceReplay {
     prepared = new Map();
     initialized = false;
     initializationPromise = null;
-    embedderUnavailableLogged = false;
+    /**
+     * #1204: whether the embedder works; retried in the background after a
+     * failure, as the pattern banks do (#1187).
+     */
+    embedderRecovery;
+    /** Whether an embedding succeeded, to label later failures as runtime ones. */
+    embedderWorked = false;
     // Real HNSW index for O(log n) similarity search (150x-12,500x faster than linear scan)
     hnswIndex;
     // Mapping from HNSW numeric IDs to experience string IDs
@@ -82,6 +89,11 @@ export class ExperienceReplay {
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.recentExperiences = new CircularBuffer(100);
+        this.embedderRecovery = new EmbedderRecovery({
+            retryIntervalMs: this.config.embedderRetryIntervalMs,
+            probe: () => probeEmbedder(this.config.embedding),
+            onRecovered: () => console.log('[ExperienceReplay] Embedder available again: similar-experience guidance uses vectors'),
+        });
         // Initialize real HNSW index with optimal parameters for experience search
         this.hnswIndex = new HNSWEmbeddingIndex({
             dimension: 384, // all-MiniLM-L6-v2 dimension
@@ -461,20 +473,36 @@ export class ExperienceReplay {
      * #1022: embed text, or return null when no embedding runtime is available.
      * The experience is then stored without a vector (backfilled at a later
      * start that has an embedder) and similarity search finds no matches.
+     * #1204: a failure is reported by getEmbedderStatus(), labelled as a
+     * runtime failure when the embedder had worked, and warned about once per
+     * outage. The embedder is retried in the background after the interval.
      */
     async embedOrNull(text) {
+        if (!this.embedderRecovery.isAvailable())
+            return null;
         try {
-            return await computeRealEmbedding(text, this.config.embedding);
+            const embedding = await computeRealEmbedding(text, this.config.embedding);
+            this.embedderWorked = true;
+            return embedding;
         }
         catch (error) {
-            if (!this.embedderUnavailableLogged) {
-                this.embedderUnavailableLogged = true;
-                console.warn('[ExperienceReplay] No embedding runtime; experiences are stored without vectors ' +
-                    'and similar-experience guidance is unavailable:', error instanceof Error ? error.message : error);
+            const message = error instanceof Error ? error.message : String(error);
+            const reason = this.embedderWorked ? `Embedder failed at runtime: ${message}` : message;
+            if (this.embedderRecovery.markUnavailable(reason)) {
+                console.warn(this.embedderWorked
+                    ? '[ExperienceReplay] Embedder failed; experiences are stored without vectors and ' +
+                        'similar-experience guidance is unavailable until it recovers:'
+                    : '[ExperienceReplay] No embedding runtime; experiences are stored without vectors ' +
+                        'and similar-experience guidance is unavailable:', message);
             }
             return null;
         }
     }
+    /** #1204: whether similar-experience guidance can use vectors, and if not why. */
+    getEmbedderStatus() {
+        const reason = this.embedderRecovery.unavailableReason;
+        return reason === null ? { mode: 'vector' } : { mode: 'unavailable', reason };
+    }
     /**
      * Get guidance for a new task based on similar experiences
      *
@@ -484,16 +512,19 @@ export class ExperienceReplay {
      */
     async getGuidance(task, domain) {
         this.ensureInitialized();
-        // #1022: the reservoir blend below picks experiences without looking at
-        // the query and gives them a coherence-derived similarity. Without an
-        // embedding of the query nothing measures relevance, so return no guidance
-        // rather than query-independent picks with a made-up similarity.
-        if (!(await this.embedOrNull(scrubReasoningBlocks(task)))) {
+        // #1022: without an embedding of the query nothing measures relevance, so
+        // return no guidance rather than picks with a made-up similarity.
+        const queryEmbedding = await this.embedOrNull(scrubReasoningBlocks(task));
+        if (!queryEmbedding) {
             return null;
         }
         // Find similar experiences via HNSW
         const similar = await this.findSimilarExperiences(task, domain);
-        // Blend in high-coherence experiences from reservoir buffer (R10, ADR-087)
+        // Blend in high-coherence experiences from reservoir buffer (R10, ADR-087).
+        // #1192: the buffer samples without looking at the query, so a sample is
+        // kept only when its similarity to the query embedding is measured and
+        // reaches the retrieval threshold. Samples without a comparable vector
+        // are skipped: every reported similarity is a measured one.
         if (this.reservoirBuffer && this.reservoirBuffer.size() > 0) {
             const reservoirSamples = this.reservoirBuffer.sample(Math.max(2, Math.floor(this.config.topK / 2)), 0.6);
             for (const entry of reservoirSamples) {
@@ -504,8 +535,12 @@ export class ExperienceReplay {
                 // Skip if domain filter doesn't match
                 if (domain && exp.domain !== domain)
                     continue;
-                // Add with a coherence-based similarity score
-                similar.push({ experience: exp, similarity: entry.coherenceScore * 0.8 });
+                if (!exp.embedding || exp.embedding.length !== queryEmbedding.length)
+                    continue;
+                const similarity = cosineSimilarity(queryEmbedding, exp.embedding);
+                if (similarity < this.config.similarityThreshold)
+                    continue;
+                similar.push({ experience: exp, similarity });
             }
         }
         if (similar.length === 0) {

package/dist/integrations/agentic-flow/reasoning-bank/index.d.ts

@@ -17,7 +17,7 @@
  */
 import { RealQEReasoningBank, type RealQEReasoningBankConfig, type RealQEPatternSearchResult, type PatternSearchStatus, type RealQERoutingRequest, type RealQERoutingResult, type LearningOutcome } from '../../../learning/real-qe-reasoning-bank.js';
 import { TrajectoryTracker, type Trajectory, type TrajectoryStep, type TrajectoryOptions, type TrajectoryTrackerConfig } from './trajectory-tracker.js';
-import { ExperienceReplay, type ExperienceGuidance, type ExperienceReplayConfig } from './experience-replay.js';
+import { ExperienceReplay, type ExperienceGuidance, type ExperienceGuidanceStatus, type ExperienceReplayConfig } from './experience-replay.js';
 import { PatternEvolution, type PatternVersion, type DriftDetectionResult, type MergeCandidate, type PatternEvolutionConfig } from './pattern-evolution.js';
 import type { QEPattern, QEDomain, CreateQEPatternOptions } from '../../../learning/qe-patterns.js';
 export interface EnhancedReasoningBankAdapterStats {
@@ -32,7 +32,7 @@ export interface EnhancedReasoningBankAdapterStats {
 }
 import type { Result } from '../../../shared/types/index.js';
 export { TrajectoryTracker, createTrajectoryTracker, type Trajectory, type TrajectoryStep, type TrajectoryOptions, type TrajectoryTrackerConfig, } from './trajectory-tracker.js';
-export { ExperienceReplay, createExperienceReplay, type Experience, type ExperienceGuidance, type ExperienceReplayConfig, } from './experience-replay.js';
+export { ExperienceReplay, createExperienceReplay, type Experience, type ExperienceGuidance, type ExperienceGuidanceStatus, type ExperienceReplayConfig, } from './experience-replay.js';
 export { PatternEvolution, createPatternEvolution, type PatternVersion, type DriftDetectionResult, type MergeCandidate, type PatternEvolutionConfig, } from './pattern-evolution.js';
 /**
  * Configuration for Enhanced ReasoningBank Adapter
@@ -185,6 +185,11 @@ export declare class EnhancedReasoningBankAdapter {
     }): Promise<Result<RealQEPatternSearchResult[]>>;
     /** #1022: whether pattern search uses vectors or text matching only. */
     getPatternSearchStatus(): PatternSearchStatus;
+    /**
+     * #1204: whether similar-experience guidance can use vectors; null when
+     * experience replay is disabled.
+     */
+    getExperienceGuidanceStatus(): ExperienceGuidanceStatus | null;
     /**
      * Record a pattern outcome with evolution tracking
      */

package/dist/integrations/agentic-flow/reasoning-bank/index.js

@@ -302,6 +302,14 @@ export class EnhancedReasoningBankAdapter {
         this.ensureInitialized();
         return this.reasoningBank.getPatternSearchStatus();
     }
+    /**
+     * #1204: whether similar-experience guidance can use vectors; null when
+     * experience replay is disabled.
+     */
+    getExperienceGuidanceStatus() {
+        this.ensureInitialized();
+        return this.experienceReplay?.getEmbedderStatus() ?? null;
+    }
     /**
      * Record a pattern outcome with evolution tracking
      */

package/dist/learning/embedder-endpoint-client.d.ts

@@ -121,6 +121,14 @@ export declare class EmbedderEndpointClient {
         failures: number;
         trippedAt: number | null;
     };
+    /**
+     * #1204: probe the endpoint while the circuit breaker is open, as its single
+     * half-open trial. Other callers keep fast-failing meanwhile. A success
+     * closes the breaker and refreshes the identity; a failure keeps the
+     * breaker open for another full window. Lets a caller that rate-limits its
+     * own retries recover without also waiting out the breaker window.
+     */
+    probeThroughOpenBreaker(): Promise<EndpointIdentity>;
     /**
      * Close the underlying keep-alive agent. Tests should call this in afterEach.
      */

package/dist/learning/embedder-endpoint-client.js

@@ -125,6 +125,10 @@ class CircuitBreaker {
         }
         return true;
     }
+    /** #1204: open (or re-open) the breaker for a full window from now. */
+    trip() {
+        this.trippedAt = Date.now();
+    }
     /** For tests / observability */
     getState() {
         return { open: this.isOpen(), failures: this.failures.length, trippedAt: this.trippedAt };
@@ -266,6 +270,22 @@ export class EmbedderEndpointClient {
     getBreakerState() {
         return this.breaker.getState();
     }
+    /**
+     * #1204: probe the endpoint while the circuit breaker is open, as its single
+     * half-open trial. Other callers keep fast-failing meanwhile. A success
+     * closes the breaker and refreshes the identity; a failure keeps the
+     * breaker open for another full window. Lets a caller that rate-limits its
+     * own retries recover without also waiting out the breaker window.
+     */
+    async probeThroughOpenBreaker() {
+        try {
+            return await this.probe();
+        }
+        catch (err) {
+            this.breaker.trip();
+            throw err;
+        }
+    }
     /**
      * Close the underlying keep-alive agent. Tests should call this in afterEach.
      */

package/dist/learning/embedder-recovery.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Embedder recovery after a failure (#1187, #1204)
+ *
+ * A consumer of the embedder (a pattern bank, ExperienceReplay) runs without
+ * vectors while its embedder is down: patterns are stored text-only and
+ * searched by text. This class tracks that state and retries the embedder
+ * after a bounded interval, so a short outage does not last until restart.
+ *
+ * The retry runs in the background. The call that finds a retry due still
+ * gets "unavailable" and carries on without vectors, so a slow or unreachable
+ * embedder host never stalls it. The consumer becomes available again only
+ * after the retry's probe has succeeded: it never reports vectors it does not
+ * have. ADR-097 still holds: nothing here produces a substitute vector.
+ */
+import { type EmbeddingConfig } from './real-embeddings.js';
+export declare const DEFAULT_EMBEDDER_RETRY_INTERVAL_MS = 60000;
+export interface EmbedderRecoveryOptions {
+    /** Wait this long after a failure before trying the embedder again. */
+    retryIntervalMs?: number;
+    /**
+     * Resolve once the embedder works and the consumer is ready to use
+     * vectors again; throw otherwise. Defaults to probeEmbedder().
+     */
+    probe?: () => Promise<void>;
+    /** Called after a retry succeeded. */
+    onRecovered?: () => void;
+    /** Called after a retry failed. */
+    onRetryFailed?: (error: unknown) => void;
+}
+/**
+ * Probe the embedder after a failure: re-initialize it, or try the endpoint
+ * through its open circuit breaker (recheckEmbedder), then embed the canary,
+ * bypassing the cache — a cached vector proves nothing about the embedder now.
+ */
+export declare function probeEmbedder(config?: Partial<EmbeddingConfig>): Promise<void>;
+export declare class EmbedderRecovery {
+    private readonly options;
+    private reason;
+    private failedAt;
+    /** Counts failures, so a retry does not clear one recorded while it ran. */
+    private failureCount;
+    private retry;
+    private readonly retryIntervalMs;
+    private readonly probe;
+    constructor(options?: EmbedderRecoveryOptions);
+    /** Why the embedder is unavailable, or null while it works. */
+    get unavailableReason(): string | null;
+    /**
+     * True when the embedder can be used now. When it cannot and a retry is
+     * due, starts one in the background and still returns false.
+     */
+    isAvailable(): boolean;
+    /**
+     * Record an embedder failure. Returns true when the embedder was available
+     * until now, so the caller can warn once per outage rather than per call.
+     */
+    markUnavailable(reason: string): boolean;
+    /** Resolves once an in-flight retry has finished (tests, shutdown). */
+    whenRetrySettled(): Promise<void>;
+    private startRetryIfDue;
+    private runRetry;
+}
+//# sourceMappingURL=embedder-recovery.d.ts.map

package/dist/learning/embedder-recovery.js

@@ -0,0 +1,94 @@
+/**
+ * Embedder recovery after a failure (#1187, #1204)
+ *
+ * A consumer of the embedder (a pattern bank, ExperienceReplay) runs without
+ * vectors while its embedder is down: patterns are stored text-only and
+ * searched by text. This class tracks that state and retries the embedder
+ * after a bounded interval, so a short outage does not last until restart.
+ *
+ * The retry runs in the background. The call that finds a retry due still
+ * gets "unavailable" and carries on without vectors, so a slow or unreachable
+ * embedder host never stalls it. The consumer becomes available again only
+ * after the retry's probe has succeeded: it never reports vectors it does not
+ * have. ADR-097 still holds: nothing here produces a substitute vector.
+ */
+import { computeRealEmbedding, recheckEmbedder, } from './real-embeddings.js';
+import { EMBEDDING_SPACE_CANARY } from './embedding-space.js';
+export const DEFAULT_EMBEDDER_RETRY_INTERVAL_MS = 60_000;
+/**
+ * Probe the embedder after a failure: re-initialize it, or try the endpoint
+ * through its open circuit breaker (recheckEmbedder), then embed the canary,
+ * bypassing the cache — a cached vector proves nothing about the embedder now.
+ */
+export async function probeEmbedder(config = {}) {
+    await recheckEmbedder(config);
+    await computeRealEmbedding(EMBEDDING_SPACE_CANARY, { ...config, enableCache: false });
+}
+export class EmbedderRecovery {
+    options;
+    reason = null;
+    failedAt = 0;
+    /** Counts failures, so a retry does not clear one recorded while it ran. */
+    failureCount = 0;
+    retry = null;
+    retryIntervalMs;
+    probe;
+    constructor(options = {}) {
+        this.options = options;
+        this.retryIntervalMs = options.retryIntervalMs ?? DEFAULT_EMBEDDER_RETRY_INTERVAL_MS;
+        this.probe = options.probe ?? (() => probeEmbedder());
+    }
+    /** Why the embedder is unavailable, or null while it works. */
+    get unavailableReason() {
+        return this.reason;
+    }
+    /**
+     * True when the embedder can be used now. When it cannot and a retry is
+     * due, starts one in the background and still returns false.
+     */
+    isAvailable() {
+        if (this.reason === null)
+            return true;
+        this.startRetryIfDue();
+        return false;
+    }
+    /**
+     * Record an embedder failure. Returns true when the embedder was available
+     * until now, so the caller can warn once per outage rather than per call.
+     */
+    markUnavailable(reason) {
+        const wasAvailable = this.reason === null;
+        this.reason = reason;
+        this.failedAt = Date.now();
+        this.failureCount++;
+        return wasAvailable;
+    }
+    /** Resolves once an in-flight retry has finished (tests, shutdown). */
+    async whenRetrySettled() {
+        await this.retry;
+    }
+    startRetryIfDue() {
+        if (this.retry)
+            return;
+        if (Date.now() - this.failedAt < this.retryIntervalMs)
+            return;
+        this.retry = this.runRetry().finally(() => {
+            this.retry = null;
+        });
+    }
+    async runRetry() {
+        const failuresBefore = this.failureCount;
+        try {
+            await this.probe();
+            if (this.failureCount !== failuresBefore)
+                return;
+            this.reason = null;
+            this.options.onRecovered?.();
+        }
+        catch (error) {
+            this.failedAt = Date.now();
+            this.options.onRetryFailed?.(error);
+        }
+    }
+}
+//# sourceMappingURL=embedder-recovery.js.map

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

@@ -38,6 +38,11 @@ export interface QEReasoningBankConfig {
     coherenceThreshold?: number;
     /** Optional RVF dual-writer for vector replication (Phase 3) */
     rvfDualWriter?: RvfDualWriter;
+    /**
+     * #1204: after the embedder fails, wait this long before trying it again
+     * (in the background). Until then patterns are stored and searched by text.
+     */
+    embedderRetryIntervalMs?: number;
 }
 /**
  * Default configuration

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

@@ -50,6 +50,11 @@ export declare class QEReasoningBank implements IQEReasoningBank {
     private readonly coherenceService?;
     private readonly config;
     private readonly embeddingProvenance;
+    /**
+     * #1187/#1204: whether the embedder works. While it does not, patterns are
+     * stored text-only and searched by text; it is retried in the background.
+     */
+    private readonly embedderRecovery;
     private patternStore;
     private initialized;
     private sqliteStore;
@@ -168,6 +173,22 @@ export declare class QEReasoningBank implements IQEReasoningBank {
      * for ARM64 or when transformers module cannot be loaded.
      */
     embed(text: string): Promise<number[]>;
+    /**
+     * #1187: embed for pattern store, search and routing, or null when the
+     * embedder endpoint fails at runtime. Callers then store the pattern
+     * text-only and search by text, as they do without an embedding runtime.
+     * ADR-097 still holds: no hash vector stands in for an endpoint vector.
+     * #1204: after a failure the embedder is not called again until a
+     * background retry, due `embedderRetryIntervalMs` later, finds it working.
+     */
+    private embedForPatterns;
+    /**
+     * #1204: why the embedder failed, while patterns are stored and searched
+     * by text only because of that failure; null while it works or was never
+     * needed. A missing embedding runtime with no endpoint configured is not a
+     * failure: there embed() returns a hash vector, which is stored text-only.
+     */
+    getEmbedderFailure(): string | null;
     /**
      * Get statistics
      */