agentic-qe 3.15.7 → 3.15.9

package/dist/domains/test-execution/services/test-executor.js

@@ -17,6 +17,7 @@ import { secureRandom, secureRandomInt } from '../../../shared/utils/crypto-rand
 import { writeTestRunEvidence } from '../../quality-assessment/quality-evidence.js';
 import { istanbulLineHits } from '../../../coordination/handlers/handler-utils.js';
 import { fileCoverageKey } from '../../coverage-analysis/collected-metrics.js';
+import { mergeTestCases, testCasesFromRunnerReport } from './runner-test-cases.js';
 import { getTestRunnerExecutionError, TestRunnerExecutionError } from '../../../shared/test-runner-verdict.js';
 import { createVitestJsonReport } from '../../../shared/vitest-json-report.js';
 import { jestExactPathPattern, runnerFilePath } from '../../../shared/test-runner-args.js';
@@ -76,6 +77,7 @@ export class TestExecutorService {
                 skipped: results.skipped,
                 duration,
                 failedTests: results.failedTests,
+                ...(results.testCases ? { testCases: results.testCases } : {}),
                 coverage: results.coverage,
                 fileCoverages: results.fileCoverages,
             };
@@ -131,6 +133,7 @@ export class TestExecutorService {
                 skipped: aggregated.skipped,
                 duration,
                 failedTests: aggregated.failedTests,
+                ...(aggregated.testCases ? { testCases: aggregated.testCases } : {}),
                 coverage: aggregated.coverage,
                 fileCoverages: aggregated.fileCoverages,
             };
@@ -331,12 +334,14 @@ Provide:
             ? this.mergeSequentialCoverage(executionResults)
             : undefined;
         const separateRuns = testFiles.length > 1 && !this.config.simulateForTesting;
+        const testCases = mergeTestCases(executionResults);
         return {
             total: passed + failed + skipped,
             passed,
             failed,
             skipped,
             failedTests,
+            ...(testCases ? { testCases } : {}),
             coverage: separateRuns ? merged?.summary : this.aggregateCoverage(coverages),
             fileCoverages: separateRuns ? merged?.perFile
                 : allFileCoverages.length > 0 ? allFileCoverages : undefined,
@@ -502,7 +507,7 @@ Provide:
                     return;
                 }
                 if (reportText === undefined) {
-                    finish(err(new Error(`The current Vitest JSON report is missing for ${fileLabel}.`)));
+                    finish(err(new TestRunnerExecutionError(`The current Vitest JSON report is missing for ${fileLabel}.`)));
                     return;
                 }
                 const parseResult = this.parseTestOutput(reportText, stderr, fileLabel, framework, code);
@@ -702,12 +707,14 @@ Provide:
                 if (executionError)
                     return err(executionError);
                 const covData = this.extractCoverageFromJson(json);
+                const testCases = this.reportedTestCases(json, file, passed + failed + skipped);
                 return ok({
                     total: passed + failed + skipped,
                     passed,
                     failed,
                     skipped,
                     failedTests,
+                    ...(testCases ? { testCases } : {}),
                     coverage: covData.summary,
                     fileCoverages: covData.perFile.length > 0 ? covData.perFile : undefined,
                     rawCoverageMap: isRecord(json.coverageMap) && !json.coverageMap.total ? json.coverageMap : undefined,
@@ -721,6 +728,14 @@ Provide:
         // Example: "Tests  5 passed | 1 failed | 1 skipped (7)"
         return this.parseTestSummaryLine(stdout, stderr, file, exitCode);
     }
+    /**
+     * #1110: the report's per-test entries, kept only when they account for
+     * every counted test; a partial list would misstate the run.
+     */
+    reportedTestCases(json, file, total) {
+        const cases = testCasesFromRunnerReport(json, file);
+        return cases && cases.length === total ? cases : undefined;
+    }
     /**
      * Parse jest JSON output
      */
@@ -757,12 +772,14 @@ Provide:
             if (executionError)
                 return err(executionError);
             const covData = this.extractCoverageFromJson(json);
+            const testCases = this.reportedTestCases(json, file, passed + failed + skipped);
             return ok({
                 total: passed + failed + skipped,
                 passed,
                 failed,
                 skipped,
                 failedTests,
+                ...(testCases ? { testCases } : {}),
                 coverage: covData.summary,
                 fileCoverages: covData.perFile.length > 0 ? covData.perFile : undefined,
                 rawCoverageMap: isRecord(json.coverageMap) && !json.coverageMap.total ? json.coverageMap : undefined,
@@ -991,6 +1008,9 @@ Provide:
             aggregated.skipped += result.skipped;
             aggregated.failedTests.push(...result.failedTests);
         }
+        const testCases = mergeTestCases(results);
+        if (testCases)
+            aggregated.testCases = testCases;
         aggregated.coverage = this.aggregateCoverage(results.map(r => r.coverage).filter((c) => c !== undefined));
         // Collect per-file coverages from all worker results
         const allFileCoverages = results.flatMap(r => r.fileCoverages ?? []);
@@ -1182,7 +1202,9 @@ Provide:
         // #1028 N1: the record names the test files it ran, so per-test duration
         // is compared only between runs of the same test set.
         const files = testFiles && testFiles.length > 0 ? [...new Set(testFiles)].sort() : undefined;
-        await this.memory.set(`test-run:${runId}`, files ? { ...result, testFiles: files } : result, {
+        // Per-test entries are returned to the caller, not persisted with the run record.
+        const { testCases: _testCases, ...record } = result;
+        await this.memory.set(`test-run:${runId}`, files ? { ...record, testFiles: files } : record, {
             namespace: 'test-execution',
             persist: true,
         });

package/dist/init/fleet-integration.js

@@ -120,6 +120,8 @@ export class FleetInitEnhancer {
             const kgService = new KnowledgeGraphService(memory, {
                 namespace: 'code-intelligence:kg',
                 enableVectorEmbeddings: true,
+                // #1096: indexing is confined to the project being initialized.
+                projectRoot: this.projectRoot,
             });
             // Find all source files
             const { glob } = await import('tinyglobby');

package/dist/init/init-wizard-steps.js

@@ -199,6 +199,8 @@ export async function runCodeIntelligenceScan(projectPath) {
         const kgService = new KnowledgeGraphService(memory, {
             namespace: 'code-intelligence:kg',
             enableVectorEmbeddings: true,
+            // #1096: indexing is confined to the project being initialized.
+            projectRoot: projectPath,
         });
         const { glob } = await import('tinyglobby');
         const files = await glob([

package/dist/init/phases/06-code-intelligence.js

@@ -223,6 +223,8 @@ export class CodeIntelligencePhase extends BasePhase {
         const kgService = new KnowledgeGraphService(memory, {
             namespace: 'code-intelligence:kg',
             enableVectorEmbeddings: true,
+            // #1096: indexing is confined to the project being initialized.
+            projectRoot,
         });
         try {
             let filesToIndex;

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

@@ -204,7 +204,8 @@ if (binCandidate && binCandidate.endsWith('bundle.js')) {
 
 appendFileSync(logFile, '[' + ts + '] Using: ' + mcpCmd + ' ' + mcpArgs.join(' ') + '\\n');
 
-const env = { ...process.env, AQE_STORAGE_PATH: '.agentic-qe', AQE_LEARNING_ENABLED: 'true', AQE_WORKERS_ENABLED: 'true', AQE_HTTP_PORT: '0' };
+// #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: process.env.AQE_WORKERS_ENABLED ?? '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));

package/dist/kernel/anti-drift-middleware.d.ts

@@ -110,7 +110,11 @@ export interface AntiDriftStats {
     readonly totalChecked: number;
     readonly driftCount: number;
     readonly averageSimilarity: number;
+    /** Events delivered without verification because the embedder failed. */
+    readonly unverifiedCount: number;
 }
+/** True when the event type is a lifecycle / control-plane event that must never be dropped. */
+export declare function isControlPlaneEvent(eventType: string): boolean;
 /**
  * Middleware enforcing semantic stability of domain events across agent-hop
  * boundaries. `onEmit` computes an embedding and attaches a SemanticFingerprint;
@@ -124,6 +128,15 @@ export declare class SemanticAntiDriftMiddleware implements EventMiddleware {
     private totalChecked;
     private driftCount;
     private similaritySum;
+    private unverifiedCount;
+    /** Suppressed drift warnings of keys evicted from the rate limiter, reported on the next warning. */
+    private evictedSuppressedWarnings;
+    /** Rate limit for drift warnings, keyed by event type and source. */
+    private readonly driftWarnings;
+    /** Payload text each fingerprint was computed from (same-process events only). */
+    private readonly emittedPayloadText;
+    private embeddingWarningAt;
+    private suppressedEmbeddingWarnings;
     constructor(config?: Partial<AntiDriftConfig>);
     /**
      * Compute the semantic embedding of the event payload and attach a
@@ -134,11 +147,13 @@ export declare class SemanticAntiDriftMiddleware implements EventMiddleware {
     onEmit(event: DomainEvent): Promise<DomainEvent>;
     /**
      * Re-embed the payload and compare with the original fingerprint.
-     * If drift exceeds threshold the event is dropped (returns null) and a
-     * SemanticDriftDetectedEvent is emitted. Events without a fingerprint
-     * pass through unchanged.
+     * If drift exceeds threshold a warning is logged, a SemanticDriftDetectedEvent
+     * is emitted, and a data event is dropped (returns null). Control-plane
+     * events (see {@link isControlPlaneEvent}) are delivered anyway: dropping a
+     * lifecycle event leaks Queen slots (#1070, #1077). Events without a
+     * fingerprint pass through unchanged.
      * @param event - The incoming domain event.
-     * @returns The event with incremented hopCount, or null if drifted.
+     * @returns The event with incremented hopCount, or null if a drifted data event.
      */
     onReceive(event: DomainEvent): Promise<DomainEvent | null>;
     /** Returns recent drift check results (bounded by maxHistorySize). */
@@ -150,10 +165,34 @@ export declare class SemanticAntiDriftMiddleware implements EventMiddleware {
      * @returns ok(void) if valid, err(Error) otherwise.
      */
     validateConfig(): Result<void, Error>;
-    /** Compute embedding, preferring transformer pipeline with hash fallback. */
+    /**
+     * Compute embedding, preferring transformer pipeline with hash fallback.
+     * The transformer returns a zero vector for text it treats as non-semantic
+     * (JSON with a "metrics" key, raw arrays, mostly numeric strings). A zero
+     * vector has no direction, so the cosine check read it as total drift and
+     * silently dropped the event, e.g. every quality_assess TaskCompleted (#1070).
+     * Such text gets a hash embedding of the same length instead, which still
+     * detects a mutated payload.
+     */
     private embed;
+    /**
+     * Fingerprinting is advisory infrastructure, not an event-delivery dependency.
+     * A transformer can fail after its cached availability probe succeeded. Do not
+     * switch vector spaces mid-event: an old semantic vector and a new hash vector
+     * cannot be compared. Deliver this event without claiming a completed check;
+     * later events still try the transformer normally.
+     */
+    private embedForEvent;
     /** Map event type to threshold category via substring matching. */
     private resolveCategory;
+    /**
+     * Log a drift detection to stderr (via the structured logger). Never logs
+     * payload contents. Rate limited per event type and source so a flood of
+     * drifted events produces one line per window plus a suppressed count.
+     */
+    private warnDrift;
+    /** Drop the least recently warned key, carrying its suppressed count forward. */
+    private evictOldestDriftWarning;
     /** Fire a SemanticDriftDetectedEvent via the configured callback. */
     private emitDriftEvent;
 }

package/dist/kernel/anti-drift-middleware.js

@@ -166,6 +166,26 @@ const DEFAULT_CONFIG = {
     maxHistorySize: 200,
     fallbackDimension: 64,
 };
+/**
+ * Control-plane (task/agent/workflow lifecycle) events, matched on the last
+ * dot-separated segment of the event type:
+ * - every `Queen*` event (QueenCoordinator prefixes all of its events),
+ * - `Task*`, `Agent*`, `Workflow*`, `Step*`, `Protocol*` and `Action*` events
+ *   (TaskCompleted, TaskFailed, workflow.StepCompleted, coordination.ProtocolFailed, ...).
+ * The Queen, the workflow orchestrator and the protocol executor count slots
+ * and advance state machines on these events, so losing one leaks a slot or
+ * hangs a run (#1070, #1077).
+ */
+const CONTROL_PLANE_EVENT_RE = /^(?:Queen[A-Z]|(?:Task|Agent|Workflow|Step|Protocol|Action)[A-Z])/;
+/** True when the event type is a lifecycle / control-plane event that must never be dropped. */
+export function isControlPlaneEvent(eventType) {
+    const name = eventType.slice(eventType.lastIndexOf('.') + 1);
+    return CONTROL_PLANE_EVENT_RE.test(name);
+}
+/** One warning per event type and source per window; later drops in the window are counted. */
+const DRIFT_WARN_WINDOW_MS = 60_000;
+/** Bound on distinct (type, source) keys tracked for warning rate limiting. */
+const DRIFT_WARN_MAX_KEYS = 256;
 /**
  * Deterministic pseudo-embedding via FNV-1a-inspired hash spread.
  * Not semantically meaningful but sufficient for detecting payload mutations.
@@ -241,6 +261,15 @@ export class SemanticAntiDriftMiddleware {
     totalChecked = 0;
     driftCount = 0;
     similaritySum = 0;
+    unverifiedCount = 0;
+    /** Suppressed drift warnings of keys evicted from the rate limiter, reported on the next warning. */
+    evictedSuppressedWarnings = 0;
+    /** Rate limit for drift warnings, keyed by event type and source. */
+    driftWarnings = new Map();
+    /** Payload text each fingerprint was computed from (same-process events only). */
+    emittedPayloadText = new WeakMap();
+    embeddingWarningAt = -Infinity;
+    suppressedEmbeddingWarnings = 0;
     constructor(config) {
         this.config = {
             ...DEFAULT_CONFIG,
@@ -256,7 +285,9 @@ export class SemanticAntiDriftMiddleware {
      */
     async onEmit(event) {
         const payloadText = JSON.stringify(event.payload);
-        const embedding = await this.embed(payloadText);
+        const embedding = await this.embedForEvent(payloadText, event, 'emit');
+        if (embedding === null)
+            return event;
         const category = this.resolveCategory(event.type);
         const threshold = this.config.thresholds[category] ?? this.config.thresholds['default'];
         const fingerprint = {
@@ -266,23 +297,38 @@ export class SemanticAntiDriftMiddleware {
             hopCount: 0,
             emittedAt: Date.now(),
         };
+        this.emittedPayloadText.set(fingerprint, payloadText);
         return { ...event, semanticFingerprint: fingerprint };
     }
     /**
      * Re-embed the payload and compare with the original fingerprint.
-     * If drift exceeds threshold the event is dropped (returns null) and a
-     * SemanticDriftDetectedEvent is emitted. Events without a fingerprint
-     * pass through unchanged.
+     * If drift exceeds threshold a warning is logged, a SemanticDriftDetectedEvent
+     * is emitted, and a data event is dropped (returns null). Control-plane
+     * events (see {@link isControlPlaneEvent}) are delivered anyway: dropping a
+     * lifecycle event leaks Queen slots (#1070, #1077). Events without a
+     * fingerprint pass through unchanged.
      * @param event - The incoming domain event.
-     * @returns The event with incremented hopCount, or null if drifted.
+     * @returns The event with incremented hopCount, or null if a drifted data event.
      */
     async onReceive(event) {
         const fp = event.semanticFingerprint;
         if (!fp)
             return event;
         const payloadText = JSON.stringify(event.payload);
-        const currentEmbedding = await this.embed(payloadText);
-        const similarity = cosineSimilarity(currentEmbedding, fp.embedding);
+        // A payload whose text is byte-identical to the text this instance
+        // fingerprinted at emit time has similarity 1 by construction; skip the
+        // second model inference (#1077).
+        let similarity = 1;
+        const emittedText = this.emittedPayloadText.get(fp);
+        // Release the cached text now: bus history keeps the emitted fingerprint
+        // alive for up to 10k events.
+        this.emittedPayloadText.delete(fp);
+        if (emittedText !== payloadText) {
+            const currentEmbedding = await this.embedForEvent(payloadText, event, 'receive');
+            if (currentEmbedding === null)
+                return event;
+            similarity = cosineSimilarity(currentEmbedding, fp.embedding);
+        }
         const distance = 1 - similarity;
         const drifted = distance > fp.driftThreshold;
         this.totalChecked++;
@@ -300,8 +346,11 @@ export class SemanticAntiDriftMiddleware {
             this.history.shift();
         if (drifted) {
             this.driftCount++;
+            const deliver = isControlPlaneEvent(event.type);
+            this.warnDrift(event, checkResult, deliver);
             await this.emitDriftEvent(event, checkResult);
-            return null;
+            if (!deliver)
+                return null;
         }
         const updatedFingerprint = { ...fp, hopCount: fp.hopCount + 1 };
         return { ...event, semanticFingerprint: updatedFingerprint };
@@ -316,6 +365,7 @@ export class SemanticAntiDriftMiddleware {
             totalChecked: this.totalChecked,
             driftCount: this.driftCount,
             averageSimilarity: this.totalChecked > 0 ? this.similaritySum / this.totalChecked : 0,
+            unverifiedCount: this.unverifiedCount,
         };
     }
     /**
@@ -334,13 +384,57 @@ export class SemanticAntiDriftMiddleware {
             return err(new Error('fallbackDimension must be positive'));
         return ok(undefined);
     }
-    /** Compute embedding, preferring transformer pipeline with hash fallback. */
+    /**
+     * Compute embedding, preferring transformer pipeline with hash fallback.
+     * The transformer returns a zero vector for text it treats as non-semantic
+     * (JSON with a "metrics" key, raw arrays, mostly numeric strings). A zero
+     * vector has no direction, so the cosine check read it as total drift and
+     * silently dropped the event, e.g. every quality_assess TaskCompleted (#1070).
+     * Such text gets a hash embedding of the same length instead, which still
+     * detects a mutated payload.
+     */
     async embed(text) {
         const hasTransformer = await probeTransformer();
-        if (hasTransformer && _computeRealEmbedding)
-            return _computeRealEmbedding(text);
+        if (hasTransformer && _computeRealEmbedding) {
+            const embedding = await _computeRealEmbedding(text);
+            if (embedding.some(v => v !== 0))
+                return embedding;
+            return hashBasedEmbedding(text, embedding.length || this.config.fallbackDimension);
+        }
         return hashBasedEmbedding(text, this.config.fallbackDimension);
     }
+    /**
+     * Fingerprinting is advisory infrastructure, not an event-delivery dependency.
+     * A transformer can fail after its cached availability probe succeeded. Do not
+     * switch vector spaces mid-event: an old semantic vector and a new hash vector
+     * cannot be compared. Deliver this event without claiming a completed check;
+     * later events still try the transformer normally.
+     */
+    async embedForEvent(text, event, stage) {
+        try {
+            return await this.embed(text);
+        }
+        catch {
+            // Counted even when the warning below is rate limited, so an outage
+            // stays visible in getStats().
+            this.unverifiedCount++;
+            const now = Date.now();
+            if (now - this.embeddingWarningAt < DRIFT_WARN_WINDOW_MS) {
+                this.suppressedEmbeddingWarnings++;
+            }
+            else {
+                logger.warn('Anti-drift embedding unavailable; event delivered without verification', {
+                    eventType: event.type, source: event.source, stage,
+                    suppressedSinceLastWarning: this.suppressedEmbeddingWarnings,
+                });
+                this.embeddingWarningAt = now;
+                this.suppressedEmbeddingWarnings = 0;
+            }
+            // Never log the payload or provider's error text (it may contain input or
+            // credentials), and never count an unavailable check as successful/drifted.
+            return null;
+        }
+    }
     /** Map event type to threshold category via substring matching. */
     resolveCategory(eventType) {
         const lower = eventType.toLowerCase();
@@ -350,6 +444,48 @@ export class SemanticAntiDriftMiddleware {
         }
         return 'default';
     }
+    /**
+     * Log a drift detection to stderr (via the structured logger). Never logs
+     * payload contents. Rate limited per event type and source so a flood of
+     * drifted events produces one line per window plus a suppressed count.
+     */
+    warnDrift(event, check, delivered) {
+        const key = `${event.type}|${String(event.source)}`;
+        const now = Date.now();
+        const entry = this.driftWarnings.get(key);
+        if (entry && now - entry.lastAt < DRIFT_WARN_WINDOW_MS) {
+            entry.suppressed++;
+            return;
+        }
+        if (!entry && this.driftWarnings.size >= DRIFT_WARN_MAX_KEYS)
+            this.evictOldestDriftWarning();
+        const suppressed = entry?.suppressed ?? 0;
+        const evictedSuppressed = this.evictedSuppressedWarnings;
+        this.evictedSuppressedWarnings = 0;
+        // Re-insert so Map order tracks lastAt and the first key is the oldest.
+        this.driftWarnings.delete(key);
+        this.driftWarnings.set(key, { lastAt: now, suppressed: 0 });
+        logger.warn(delivered
+            ? 'Semantic drift detected on a control-plane event; delivered anyway'
+            : 'Semantic drift detected; event dropped', {
+            eventType: event.type,
+            source: event.source,
+            cosineSimilarity: Number(check.cosineSimilarity.toFixed(4)),
+            cosineDistance: Number((1 - check.cosineSimilarity).toFixed(4)),
+            threshold: check.threshold,
+            hopCount: check.hopCount,
+            ...(suppressed > 0 ? { suppressedSinceLastWarning: suppressed } : {}),
+            ...(evictedSuppressed > 0 ? { suppressedForEvictedKeys: evictedSuppressed } : {}),
+        });
+    }
+    /** Drop the least recently warned key, carrying its suppressed count forward. */
+    evictOldestDriftWarning() {
+        const oldest = this.driftWarnings.keys().next();
+        if (oldest.done)
+            return;
+        this.evictedSuppressedWarnings += this.driftWarnings.get(oldest.value)?.suppressed ?? 0;
+        this.driftWarnings.delete(oldest.value);
+    }
     /** Fire a SemanticDriftDetectedEvent via the configured callback. */
     async emitDriftEvent(originalEvent, check) {
         if (!this.config.onDriftDetected)

package/dist/kernel/interfaces.d.ts

@@ -33,6 +33,11 @@ export interface DomainPlugin extends Initializable, Disposable {
      * @returns true if domain can handle the task type
      */
     canHandleTask?(taskType: string): boolean;
+    /**
+     * Task types this domain executes through `executeTask` (#1075).
+     * Optional - used to tell callers which types a domain accepts.
+     */
+    getSupportedTaskTypes?(): string[];
 }
 export interface DomainHealth {
     /**

package/dist/learning/dream/dream-engine.d.ts

@@ -31,7 +31,21 @@ export interface DreamConfig {
     activationConfig: ActivationConfig;
     /** Insight generation configuration */
     insightConfig: InsightConfig;
-    /** Enable RVCOW branching for reversible dream cycles (ADR-069). Default: true */
+    /**
+     * Enable RVCOW branching for reversible dream cycles (ADR-069).
+     * Default: false (#1060).
+     *
+     * RISK — opt in only for an isolated database connection. The branch is a
+     * SQLite SAVEPOINT on the process-wide shared connection, and it stays open
+     * for the whole asynchronous dream (up to `maxDurationMs`). Every other
+     * write made on that connection in the meantime (memory_store, pattern
+     * updates, experience capture) joins the savepoint. A discard (failed
+     * validation, error, cancel) rolls those foreground writes back even though
+     * they were already acknowledged. Branch validation only inspects
+     * `qe_patterns`, which `dream()` does not write, so branching adds little
+     * protection to a dream cycle. A compute-then-commit rework is tracked in
+     * #1060.
+     */
     enableBranching: boolean;
     /** Validation thresholds for dream branch quality checks */
     branchValidationThresholds: ValidationThresholds;
@@ -104,6 +118,8 @@ export declare class DreamEngine {
     private graph;
     private db;
     private branchManager;
+    /** #1060: marks the in-flight dream cycle interrupted (set while dreaming). */
+    private interruptActiveDream;
     private currentCycle;
     private initialized;
     private cancelled;
@@ -138,6 +154,15 @@ export declare class DreamEngine {
      * @returns Dream cycle result with insights and statistics
      */
     dream(durationMs?: number): Promise<DreamCycleResult>;
+    /**
+     * #1060: build a synchronous handler that records a still-running cycle as
+     * 'interrupted'. It runs from close() and from a process store closer,
+     * which runs before the shared database closes (closers run newest first).
+     * When opt-in branching left a savepoint open, the savepoint is released
+     * first so foreground writes made on the shared connection during the
+     * dream are committed rather than lost with the connection.
+     */
+    private createCycleInterrupter;
     /**
      * Load patterns as concepts for dreaming.
      *
@@ -203,6 +228,7 @@ export declare class DreamEngine {
     getCurrentCycle(): DreamCycle | null;
     private saveCycle;
     private updateCycle;
+    private updateCycleSync;
     private saveInsight;
     private getInsightRowById;
     /**

package/dist/learning/dream/dream-engine.js

@@ -21,6 +21,7 @@ import { LoggerFactory } from '../../logging/index.js';
 const dreamLogger = LoggerFactory.create('dream-engine');
 import { v4 as uuidv4 } from 'uuid';
 import { getUnifiedPersistence } from '../../kernel/unified-persistence.js';
+import { registerStoreCloser } from '../../kernel/process-lifecycle.js';
 import { ConceptGraph } from './concept-graph.js';
 import { SpreadingActivation, } from './spreading-activation.js';
 import { InsightGenerator, } from './insight-generator.js';
@@ -43,7 +44,8 @@ export const DEFAULT_DREAM_CONFIG = {
         minConfidence: 0.5,
         maxInsightsPerCycle: 10,
     },
-    enableBranching: true,
+    // #1060: off by default; see the RISK note on DreamConfig.enableBranching.
+    enableBranching: false,
     branchValidationThresholds: { ...DEFAULT_VALIDATION_THRESHOLDS },
 };
 // ============================================================================
@@ -206,6 +208,8 @@ export class DreamEngine {
     graph = null;
     db = null;
     branchManager = null;
+    /** #1060: marks the in-flight dream cycle interrupted (set while dreaming). */
+    interruptActiveDream = null;
     currentCycle = null;
     initialized = false;
     cancelled = false;
@@ -344,13 +348,18 @@ export class DreamEngine {
             status: 'running',
         };
         await this.saveCycle(this.currentCycle);
-        // ADR-069: Create RVCOW branch before dream consolidation
+        // ADR-069: Create RVCOW branch before dream consolidation (opt-in, #1060)
         let branch = null;
         if (this.branchManager) {
             const branchName = `dream-${this.currentCycle.id}-${Date.now()}`;
             branch = this.branchManager.createBranch(branchName);
             this.emitBranchEvent('dream:branch_created', branch);
         }
+        // #1060: if the engine closes or the process shuts down mid-dream, record
+        // the cycle as interrupted instead of leaving it 'running' forever.
+        const interrupt = this.createCycleInterrupter(this.currentCycle, startTime, () => branch);
+        this.interruptActiveDream = interrupt;
+        const unregisterShutdownGuard = registerStoreCloser(interrupt);
         try {
             // 1. Check we have enough concepts
             const allNodes = await this.graph.getActiveNodes(0);
@@ -458,6 +467,44 @@ export class DreamEngine {
             this.currentCycle = null;
             throw error;
         }
+        finally {
+            unregisterShutdownGuard();
+            if (this.interruptActiveDream === interrupt)
+                this.interruptActiveDream = null;
+        }
+    }
+    /**
+     * #1060: build a synchronous handler that records a still-running cycle as
+     * 'interrupted'. It runs from close() and from a process store closer,
+     * which runs before the shared database closes (closers run newest first).
+     * When opt-in branching left a savepoint open, the savepoint is released
+     * first so foreground writes made on the shared connection during the
+     * dream are committed rather than lost with the connection.
+     */
+    createCycleInterrupter(cycle, startTime, getBranch) {
+        return () => {
+            if (cycle.status !== 'running' || !this.db)
+                return;
+            const branch = getBranch();
+            if (branch && this.branchManager) {
+                try {
+                    this.branchManager.mergeBranch(branch);
+                }
+                catch {
+                    // Branch already resolved; nothing to release
+                }
+            }
+            cycle.status = 'interrupted';
+            cycle.error = 'Interrupted: engine closed or process shut down during the dream cycle';
+            cycle.endTime = new Date();
+            cycle.durationMs = Date.now() - startTime;
+            try {
+                this.updateCycleSync(cycle);
+            }
+            catch {
+                // Best effort during shutdown
+            }
+        };
     }
     // ==========================================================================
     // Pattern Loading
@@ -753,6 +800,9 @@ export class DreamEngine {
         stmt.run(cycle.id, cycle.startTime.toISOString(), cycle.endTime?.toISOString() ?? null, cycle.durationMs ?? null, cycle.conceptsProcessed, cycle.associationsFound, cycle.insightsGenerated, cycle.status, cycle.error ?? null, cycle.startTime.toISOString());
     }
     async updateCycle(cycle) {
+        this.updateCycleSync(cycle);
+    }
+    updateCycleSync(cycle) {
         if (!this.db)
             return;
         const stmt = this.db.prepare(`
@@ -815,6 +865,10 @@ export class DreamEngine {
      * Release resources (does NOT close the shared database)
      */
     async close() {
+        // #1060: a dream still in flight is recorded as interrupted before the
+        // engine lets go of the database.
+        this.interruptActiveDream?.();
+        this.interruptActiveDream = null;
         if (this.graph) {
             await this.graph.close();
             this.graph = null;