agentic-qe 3.15.9 → 3.15.10

package/dist/integrations/browser/agent-browser/command-executor.js

@@ -2,9 +2,23 @@
  * agent-browser CLI Command Executor
  * Wraps CLI calls with type safety and error handling
  */
-import { spawnSync, spawn } from 'child_process';
+import { spawn } from 'child_process';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { npmCliInvocation } from '../../../shared/npm-cli-invocation.js';
+import { runProcessText, runTestRunnerProcess } from '../../../shared/test-runner-process.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
+/**
+ * Run `npx agent-browser ...` without blocking the event loop (#1115). A
+ * timeout stops the whole npx process tree, as the synchronous call did not.
+ */
+export function runAgentBrowser(args, timeout, maxBuffer) {
+    const npx = npmCliInvocation('npx');
+    if (!npx) {
+        const error = Object.assign(new Error('npx CLI not found next to node'), { code: 'ENOENT' });
+        return Promise.resolve({ status: null, signal: null, stdout: '', stderr: '', error });
+    }
+    return runTestRunnerProcess(npx[0], [...npx[1], 'agent-browser', ...args], { cwd: process.cwd(), timeout, maxBuffer });
+}
 /**
  * Execute agent-browser CLI commands with type safety
  */
@@ -27,21 +41,15 @@ export class AgentBrowserCommandExecutor {
     // Core execution methods
     // ========================================================================
     /**
-     * Execute a command synchronously and parse JSON result
+     * Execute a command and parse JSON result
      */
-    execute(command, args = []) {
+    async execute(command, args = []) {
         const fullArgs = this.buildArgs(command, args);
-        const spawnArgs = ['agent-browser', ...fullArgs];
         if (this.config.debug) {
-            console.log(`[agent-browser] Executing: npx ${spawnArgs.join(' ')}`);
+            console.log(`[agent-browser] Executing: npx agent-browser ${fullArgs.join(' ')}`);
         }
         try {
-            const result = spawnSync('npx', spawnArgs, {
-                encoding: 'utf-8',
-                timeout: this.config.timeout,
-                maxBuffer: 10 * 1024 * 1024, // 10MB for screenshots
-                shell: false,
-            });
+            const result = await runAgentBrowser(fullArgs, this.config.timeout, 10 * 1024 * 1024); // 10MB for screenshots
             if (result.error) {
                 return { success: false, error: result.error.message };
             }
@@ -110,12 +118,12 @@ export class AgentBrowserCommandExecutor {
     /**
      * Open URL in browser (auto-launches if needed)
      */
-    open(url) {
+    async open(url) {
         const args = [url];
         if (this.config.headed) {
             args.push('--headed');
         }
-        const result = this.execute('open', args);
+        const result = await this.execute('open', args);
         if (result.success) {
             this.browserLaunched = true;
         }
@@ -124,8 +132,8 @@ export class AgentBrowserCommandExecutor {
     /**
      * Close browser
      */
-    close() {
-        const result = this.execute('close');
+    async close() {
+        const result = await this.execute('close');
         if (result.success) {
             this.browserLaunched = false;
         }
@@ -136,10 +144,10 @@ export class AgentBrowserCommandExecutor {
      * CRITICAL: Must be called to prevent memory leaks!
      * The daemon persists even after close() - this kills it entirely.
      */
-    terminateDaemon() {
+    async terminateDaemon() {
         try {
             // First close the browser gracefully
-            this.close();
+            await this.close();
             // Kill all processes matching this session's daemon
             // The daemon runs as: node .../agent-browser/.../daemon.js
             // with environment variable AGENT_BROWSER_SESSION=<sessionName>
@@ -147,15 +155,10 @@ export class AgentBrowserCommandExecutor {
             // Find and kill processes by session name
             // Use pkill with argument array to prevent shell injection
             try {
-                spawnSync('pkill', ['-f', `agent-browser.*--session[= ]${sessionName}`], {
-                    timeout: 5000,
-                    stdio: 'ignore',
-                    shell: false,
-                });
+                await runProcessText('pkill', ['-f', `agent-browser.*--session[= ]${sessionName}`], { cwd: process.cwd(), timeout: 5000 });
             }
-            catch (error) {
-                // Non-critical: pkill errors - process might already be dead
-                console.debug('[CommandExecutor] pkill error:', error instanceof Error ? error.message : error);
+            catch {
+                // Non-critical: pkill exits 1 when nothing matched, or the process is already dead
             }
             // Also try to kill by AGENT_BROWSER_SESSION env var (harder to match)
             // As a fallback, we'll rely on the session-specific matching above
@@ -175,7 +178,7 @@ export class AgentBrowserCommandExecutor {
     /**
      * Get accessibility snapshot with refs
      */
-    snapshot(options) {
+    async snapshot(options) {
         const args = ['--json'];
         if (options?.interactive)
             args.push('-i');
@@ -191,32 +194,32 @@ export class AgentBrowserCommandExecutor {
     /**
      * Click element by ref or selector
      */
-    click(target) {
+    async click(target) {
         return this.execute('click', [target]);
     }
     /**
      * Fill input by ref or selector
      */
-    fill(target, text) {
+    async fill(target, text) {
         return this.execute('fill', [target, text]);
     }
     /**
      * Type text (without clearing)
      */
-    type(target, text) {
+    async type(target, text) {
         return this.execute('type', [target, text]);
     }
     /**
      * Get element text
      */
-    getText(target) {
+    async getText(target) {
         return this.execute('get', ['text', target, '--json']);
     }
     /**
      * Check if element is visible
      */
-    isVisible(target) {
-        const result = this.execute('is', ['visible', target, '--json']);
+    async isVisible(target) {
+        const result = await this.execute('is', ['visible', target, '--json']);
         if (result.success && result.data) {
             return { success: true, data: result.data.success };
         }
@@ -228,7 +231,7 @@ export class AgentBrowserCommandExecutor {
     /**
      * Take screenshot
      */
-    screenshot(path, fullPage) {
+    async screenshot(path, fullPage) {
         const args = [];
         if (path)
             args.push(path);
@@ -244,7 +247,7 @@ export class AgentBrowserCommandExecutor {
     /**
      * Wait for element
      */
-    waitForElement(target, timeout) {
+    async waitForElement(target, timeout) {
         const args = [target];
         if (timeout) {
             // Wait command accepts ms or selector
@@ -255,13 +258,13 @@ export class AgentBrowserCommandExecutor {
     /**
      * Wait for text to appear
      */
-    waitForText(text) {
+    async waitForText(text) {
         return this.execute('wait', ['--text', text]);
     }
     /**
      * Wait for URL pattern
      */
-    waitForUrl(pattern) {
+    async waitForUrl(pattern) {
         // URL pattern needs to be a glob pattern, convert simple strings
         const urlPattern = pattern.includes('*') ? pattern : `**${pattern}**`;
         return this.execute('wait', ['--url', urlPattern]);
@@ -269,7 +272,7 @@ export class AgentBrowserCommandExecutor {
     /**
      * Wait for network idle
      */
-    waitForNetworkIdle() {
+    async waitForNetworkIdle() {
         return this.execute('wait', ['--load', 'networkidle']);
     }
     // ========================================================================
@@ -278,13 +281,13 @@ export class AgentBrowserCommandExecutor {
     /**
      * Set device emulation
      */
-    setDevice(deviceName) {
+    async setDevice(deviceName) {
         return this.execute('set', ['device', deviceName]);
     }
     /**
      * Set viewport size
      */
-    setViewport(width, height) {
+    async setViewport(width, height) {
         return this.execute('set', ['viewport', String(width), String(height)]);
     }
     // ========================================================================
@@ -293,20 +296,20 @@ export class AgentBrowserCommandExecutor {
     /**
      * Mock network route
      */
-    mockRoute(urlPattern, body) {
+    async mockRoute(urlPattern, body) {
         const bodyJson = JSON.stringify(body);
         return this.execute('network', ['route', urlPattern, '--body', bodyJson]);
     }
     /**
      * Abort network route
      */
-    abortRoute(urlPattern) {
+    async abortRoute(urlPattern) {
         return this.execute('network', ['route', urlPattern, '--abort']);
     }
     /**
      * Clear network routes
      */
-    clearRoutes() {
+    async clearRoutes() {
         return this.execute('network', ['unroute']);
     }
     // ========================================================================
@@ -315,13 +318,13 @@ export class AgentBrowserCommandExecutor {
     /**
      * Save browser state (cookies, storage)
      */
-    saveState(path) {
+    async saveState(path) {
         return this.execute('state', ['save', path]);
     }
     /**
      * Load browser state
      */
-    loadState(path) {
+    async loadState(path) {
         return this.execute('state', ['load', path]);
     }
     // ========================================================================
@@ -331,15 +334,15 @@ export class AgentBrowserCommandExecutor {
      * Start trace recording
      * Records browser activity for debugging and analysis
      */
-    startTrace() {
+    async startTrace() {
         return this.execute('trace', ['start']);
     }
     /**
      * Stop trace recording and save to file
      * @param outputPath - Path to save the trace file
      */
-    stopTrace(outputPath) {
-        const result = this.execute('trace', ['stop', outputPath]);
+    async stopTrace(outputPath) {
+        const result = await this.execute('trace', ['stop', outputPath]);
         if (result.success) {
             return { success: true, data: outputPath };
         }
@@ -351,7 +354,7 @@ export class AgentBrowserCommandExecutor {
     /**
      * Evaluate JavaScript in page context
      */
-    eval(script) {
+    async eval(script) {
         return this.execute('eval', [script, '--json']);
     }
     // ========================================================================
@@ -386,15 +389,11 @@ export class AgentBrowserCommandExecutor {
 /**
  * Check if agent-browser CLI is available
  */
-export function isAgentBrowserAvailable() {
+export async function isAgentBrowserAvailable() {
     try {
         // Use 'npx agent-browser' without args to check help output
         // --version is not a valid command, but running with no args shows help
-        const result = spawnSync('npx', ['agent-browser'], {
-            encoding: 'utf-8',
-            timeout: 10000,
-            shell: false,
-        });
+        const result = await runAgentBrowser([], 10000);
         const output = (result.stdout ?? '') + (result.stderr ?? '');
         return output.includes('agent-browser') && output.includes('Usage:');
     }

package/dist/integrations/browser/agent-browser/session-manager.d.ts

@@ -56,7 +56,7 @@ export declare class AgentBrowserSessionManager {
     /**
      * List active session names from CLI
      */
-    listCliSessions(): string[];
+    listCliSessions(): Promise<string[]>;
     /**
      * Close a specific session
      */

package/dist/integrations/browser/agent-browser/session-manager.js

@@ -2,8 +2,7 @@
  * agent-browser Session Manager
  * Manages multiple isolated browser sessions for parallel testing
  */
-import { execSync } from 'child_process';
-import { AgentBrowserCommandExecutor } from './command-executor.js';
+import { AgentBrowserCommandExecutor, runAgentBrowser } from './command-executor.js';
 /**
  * Manage multiple isolated browser sessions
  */
@@ -43,7 +42,7 @@ export class AgentBrowserSessionManager {
         this.sessions.set(name, session);
         // Navigate to initial URL if provided
         if (options?.initialUrl) {
-            const result = executor.open(options.initialUrl);
+            const result = await executor.open(options.initialUrl);
             if (result.success) {
                 session.currentUrl = options.initialUrl;
                 session.status = 'active';
@@ -97,12 +96,12 @@ export class AgentBrowserSessionManager {
     /**
      * List active session names from CLI
      */
-    listCliSessions() {
+    async listCliSessions() {
         try {
-            const output = execSync('npx agent-browser session list', {
-                encoding: 'utf-8',
-                timeout: 5000,
-            });
+            const result = await runAgentBrowser(['session', 'list'], 5000);
+            if (result.error || result.status !== 0)
+                return [];
+            const output = result.stdout;
             // Parse output like:
             // Active sessions:
             // -> default
@@ -134,7 +133,7 @@ export class AgentBrowserSessionManager {
         }
         // Terminate the daemon entirely (not just close browser)
         // This is CRITICAL to prevent memory leaks - the daemon persists otherwise!
-        const result = session.executor.terminateDaemon();
+        const result = await session.executor.terminateDaemon();
         if (result.success) {
             session.status = 'closed';
             this.sessions.delete(name);

package/dist/integrations/browser/web-content-fetcher.js

@@ -12,13 +12,15 @@
  * @version 1.0.0
  * @since v3
  */
-import { exec, execSync } from 'child_process';
+import { exec } from 'child_process';
 import { promisify } from 'util';
 import * as fs from 'fs';
 import * as path from 'path';
 import { createBrowserClient, isAgentBrowserAvailable } from './client-factory.js';
 import { toErrorMessage } from '../../shared/error-utils.js';
 import { safeJsonParse } from '../../shared/safe-json.js';
+import { npmCliInvocation } from '../../shared/npm-cli-invocation.js';
+import { runProcessText } from '../../shared/test-runner-process.js';
 const execAsync = promisify(exec);
 // ============================================================================
 // WebContentFetcher Class
@@ -246,9 +248,13 @@ export class WebContentFetcher {
         if (!fs.existsSync(packageJsonPath)) {
             fs.writeFileSync(packageJsonPath, JSON.stringify({ name: 'pw-fetch', type: 'commonjs' }));
             try {
-                execSync('npm install playwright-extra puppeteer-extra-plugin-stealth playwright', {
+                // Async so the install does not block the event loop for up to 120s,
+                // and a timeout stops npm with its children (#1115).
+                const npm = npmCliInvocation('npm');
+                if (!npm)
+                    throw new Error('npm CLI not found');
+                await runProcessText(npm[0], [...npm[1], 'install', 'playwright-extra', 'puppeteer-extra-plugin-stealth', 'playwright'], {
                     cwd: workDir,
-                    stdio: 'pipe',
                     timeout: 120000,
                 });
             }

package/dist/integrations/vibium/client.js

@@ -135,7 +135,7 @@ export class VibiumClientImpl {
         try {
             // Check if Vibium package is available
             const browser = await getVibiumBrowser();
-            this._available = browser !== null && isVibiumReady();
+            this._available = browser !== null && await isVibiumReady();
             return this._available;
         }
         catch {
@@ -215,7 +215,7 @@ export class VibiumClientImpl {
             }
             // Launch REAL browser using Vibium
             const headless = options?.headless ?? this.config.headless;
-            if (!isVibiumReady()) {
+            if (!(await isVibiumReady())) {
                 throw new VibiumUnavailableError(`Vibium browser payload unavailable; run ${VIBIUM_SETUP}`);
             }
             const instance = await browser.start({ headless });

package/dist/integrations/vibium/runtime.d.ts

@@ -9,6 +9,6 @@ type Runtime = typeof import('vibium');
 export declare function npmInvocation(platform?: NodeJS.Platform, execPath?: string, exists?: (path: string) => boolean): [string, string[]];
 export declare function loadVibium(): Promise<Runtime>;
 /** Check the payload belonging to the resolved library, not a different PATH CLI. */
-export declare function isVibiumReady(): boolean;
+export declare function isVibiumReady(): Promise<boolean>;
 export {};
 //# sourceMappingURL=runtime.d.ts.map

package/dist/integrations/vibium/runtime.js

@@ -1,11 +1,18 @@
 /** Resolve the opt-in Vibium runtime for both local and global AQE installs. */
 import { createRequire } from 'node:module';
-import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { npmCliInvocation } from '../../shared/npm-cli-invocation.js';
+import { runProcessText } from '../../shared/test-runner-process.js';
 export const VIBIUM_SETUP = 'aqe init --browser-engine (or npm install vibium@^26.8.21)';
 const requireFromHere = createRequire(import.meta.url);
+/**
+ * Async probe (#1115): a slow npm or Vibium CLI must not block the MCP server,
+ * and a timeout stops its whole process group.
+ */
+function execFileText(file, args) {
+    return runProcessText(file, args, { cwd: process.cwd(), timeout: 5000 });
+}
 /**
  * How to run npm without a shell. On Windows `npm` is an `npm.cmd` shim, which
  * execFile cannot start without `shell: true` (EINVAL/ENOENT since the
@@ -16,7 +23,7 @@ export function npmInvocation(platform = process.platform, execPath = process.ex
     return npmCliInvocation('npm', platform, execPath, exists) ?? ['npm', []];
 }
 /** Never install or download anything while probing availability. */
-function resolveRuntime() {
+async function resolveRuntime() {
     try {
         return requireFromHere.resolve('vibium');
     }
@@ -28,9 +35,7 @@ function resolveRuntime() {
         // A global CLI installation is not on Node's normal module search path.
         // npm root is read-only and honors the same npm prefix as explicit setup.
         const [npmBin, npmPrefixArgs] = npmInvocation();
-        const root = execFileSync(npmBin, [...npmPrefixArgs, 'root', '-g'], {
-            encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
-        }).trim();
+        const root = (await execFileText(npmBin, [...npmPrefixArgs, 'root', '-g'])).trim();
         return requireFromHere.resolve(join(root, 'vibium'));
     }
 }
@@ -60,7 +65,7 @@ export async function loadVibium() {
             throw error;
         let entry;
         try {
-            entry = resolveRuntime();
+            entry = await resolveRuntime();
         }
         catch (cause) {
             throw new Error(`Vibium is not installed; run ${VIBIUM_SETUP}`, { cause });
@@ -75,12 +80,10 @@ export async function loadVibium() {
     return runtime;
 }
 /** Check the payload belonging to the resolved library, not a different PATH CLI. */
-export function isVibiumReady() {
+export async function isVibiumReady() {
     try {
-        const cli = join(dirname(resolveRuntime()), '..', 'bin', 'cli.js');
-        execFileSync(process.execPath, [cli, 'is-installed'], {
-            timeout: 5000, stdio: 'ignore',
-        });
+        const cli = join(dirname(await resolveRuntime()), '..', 'bin', 'cli.js');
+        await execFileText(process.execPath, [cli, 'is-installed']);
         return true;
     }
     catch {

package/dist/kernel/unified-memory-schemas.d.ts

@@ -7,8 +7,9 @@
 import { HYPERGRAPH_SCHEMA } from '../migrations/20260120_add_hypergraph_tables.js';
 import { PATTERN_NULLS_SCHEMA } from '../migrations/20260611_add_pattern_nulls_table.js';
 import { LEARNING_EVIDENCE_SCHEMA } from '../migrations/20260830_add_learning_evidence_tables.js';
-export { HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA, LEARNING_EVIDENCE_SCHEMA };
-export declare const SCHEMA_VERSION = 13;
+import { DREAM_INSIGHTS_ARCHIVE_SCHEMA } from '../migrations/20261018_add_dream_insights_archive.js';
+export { HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA, LEARNING_EVIDENCE_SCHEMA, DREAM_INSIGHTS_ARCHIVE_SCHEMA };
+export declare const SCHEMA_VERSION = 14;
 export declare const SCHEMA_VERSION_TABLE = "\n  CREATE TABLE IF NOT EXISTS schema_version (\n    id INTEGER PRIMARY KEY CHECK (id = 1),\n    version INTEGER NOT NULL,\n    migrated_at TEXT DEFAULT (datetime('now'))\n  );\n";
 export declare const KV_STORE_SCHEMA = "\n  -- Key-Value Store (v2 compatible - same schema as HybridBackend)\n  CREATE TABLE IF NOT EXISTS kv_store (\n    key TEXT NOT NULL,\n    namespace TEXT NOT NULL,\n    value TEXT NOT NULL,\n    expires_at INTEGER,\n    created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000),\n    PRIMARY KEY (namespace, key)\n  );\n  CREATE INDEX IF NOT EXISTS idx_kv_namespace ON kv_store(namespace);\n  CREATE INDEX IF NOT EXISTS idx_kv_expires ON kv_store(expires_at) WHERE expires_at IS NOT NULL;\n";
 export declare const VECTORS_SCHEMA = "\n  -- Vector Embeddings (new in v3 - replaces in-memory AgentDB)\n  CREATE TABLE IF NOT EXISTS vectors (\n    id TEXT PRIMARY KEY,\n    namespace TEXT NOT NULL DEFAULT 'default',\n    embedding BLOB NOT NULL,\n    dimensions INTEGER NOT NULL,\n    metadata TEXT,\n    created_at TEXT DEFAULT (datetime('now')),\n    updated_at TEXT DEFAULT (datetime('now'))\n  );\n  CREATE INDEX IF NOT EXISTS idx_vectors_namespace ON vectors(namespace);\n  CREATE INDEX IF NOT EXISTS idx_vectors_dimensions ON vectors(dimensions);\n";

package/dist/kernel/unified-memory-schemas.js

@@ -7,12 +7,13 @@
 import { HYPERGRAPH_SCHEMA } from '../migrations/20260120_add_hypergraph_tables.js';
 import { PATTERN_NULLS_SCHEMA } from '../migrations/20260611_add_pattern_nulls_table.js';
 import { LEARNING_EVIDENCE_SCHEMA } from '../migrations/20260830_add_learning_evidence_tables.js';
+import { DREAM_INSIGHTS_ARCHIVE_SCHEMA } from '../migrations/20261018_add_dream_insights_archive.js';
 // Re-export for convenience
-export { HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA, LEARNING_EVIDENCE_SCHEMA };
+export { HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA, LEARNING_EVIDENCE_SCHEMA, DREAM_INSIGHTS_ARCHIVE_SCHEMA };
 // ============================================================================
 // Schema Version for Migrations
 // ============================================================================
-export const SCHEMA_VERSION = 13; // v12: learning evidence; v13: embedding-space provenance (#633)
+export const SCHEMA_VERSION = 14; // v12: learning evidence; v13: embedding-space provenance (#633); v14: dream_insights_archive (#1116)
 export const SCHEMA_VERSION_TABLE = `
   CREATE TABLE IF NOT EXISTS schema_version (
     id INTEGER PRIMARY KEY CHECK (id = 1),

package/dist/kernel/unified-memory.js

@@ -41,7 +41,7 @@ export { BinaryHeap, UnifiedHnswIndex, createHnswIndex } from './unified-memory-
 // parity tests or benchmarks only.
 import { UnifiedHnswIndex } from './unified-memory-hnsw.js';
 // Import schemas
-import { SCHEMA_VERSION, SCHEMA_VERSION_TABLE, KV_STORE_SCHEMA, VECTORS_SCHEMA, RL_QVALUES_SCHEMA, GOAP_SCHEMA, DREAM_SCHEMA, QE_PATTERNS_SCHEMA, QE_PATTERNS_FTS_SCHEMA, QE_PATTERNS_SCHEMA_WITHOUT_FTS, MINCUT_SCHEMA, SONA_PATTERNS_SCHEMA, FEEDBACK_SCHEMA, HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA, STATS_TABLES, } from './unified-memory-schemas.js';
+import { SCHEMA_VERSION, SCHEMA_VERSION_TABLE, KV_STORE_SCHEMA, VECTORS_SCHEMA, RL_QVALUES_SCHEMA, GOAP_SCHEMA, DREAM_SCHEMA, QE_PATTERNS_SCHEMA, QE_PATTERNS_FTS_SCHEMA, QE_PATTERNS_SCHEMA_WITHOUT_FTS, MINCUT_SCHEMA, SONA_PATTERNS_SCHEMA, FEEDBACK_SCHEMA, HYPERGRAPH_SCHEMA, PATTERN_NULLS_SCHEMA, DREAM_INSIGHTS_ARCHIVE_SCHEMA, STATS_TABLES, } from './unified-memory-schemas.js';
 import { ensurePatternFtsInSync } from './pattern-fts-self-heal.js';
 import { applyMigration as applyLearningEvidenceMigration } from '../migrations/20260830_add_learning_evidence_tables.js';
 // CRDT imports for distributed state synchronization
@@ -432,10 +432,20 @@ export class UnifiedMemoryManager {
         this.db.exec(SCHEMA_VERSION_TABLE);
         this.handleV2SchemaIncompatibilities();
         const versionRow = this.db.prepare('SELECT version FROM schema_version WHERE id = 1').get();
-        const currentVersion = versionRow?.version ?? 0;
-        if (currentVersion < SCHEMA_VERSION) {
-            console.log(`[UnifiedMemory] Migrating from v${currentVersion} to v${SCHEMA_VERSION}`);
+        const observedVersion = versionRow?.version ?? 0;
+        if (observedVersion < SCHEMA_VERSION) {
+            console.log(`[UnifiedMemory] Migrating from v${observedVersion} to v${SCHEMA_VERSION}`);
+            // #1116: IMMEDIATE takes the write lock before the first statement, so a
+            // concurrent opener waits on busy_timeout instead of failing with
+            // SQLITE_BUSY when a deferred read transaction has to upgrade (CREATE
+            // INDEX after a CREATE TABLE IF NOT EXISTS that only read). The version is
+            // read again under that lock: a process that waited applies only what the
+            // first one left, instead of re-running steps from a stale version.
             const migrate = this.db.transaction(() => {
+                const lockedRow = this.db.prepare('SELECT version FROM schema_version WHERE id = 1').get();
+                const currentVersion = lockedRow?.version ?? 0;
+                if (currentVersion >= SCHEMA_VERSION)
+                    return currentVersion;
                 if (currentVersion < 1)
                     this.db.exec(KV_STORE_SCHEMA);
                 if (currentVersion < 2)
@@ -472,13 +482,22 @@ export class UnifiedMemoryManager {
                     applyLearningEvidenceMigration(this.db);
                 if (currentVersion < 13)
                     this.migrateToV13EmbeddingSpace();
+                // #1116: additive; a table an earlier sweep created lazily is kept with its rows.
+                if (currentVersion < 14)
+                    this.db.exec(DREAM_INSIGHTS_ARCHIVE_SCHEMA);
                 this.db.prepare(`
           INSERT OR REPLACE INTO schema_version (id, version, migrated_at)
           VALUES (1, ?, datetime('now'))
         `).run(SCHEMA_VERSION);
+                return currentVersion;
             });
-            migrate();
-            console.log(`[UnifiedMemory] Migration complete`);
+            const migratedFrom = migrate.immediate();
+            if (migratedFrom >= SCHEMA_VERSION) {
+                console.log(`[UnifiedMemory] Another process completed the migration to v${SCHEMA_VERSION}`);
+            }
+            else {
+                console.log(`[UnifiedMemory] Migration complete`);
+            }
         }
     }
     /**

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

@@ -0,0 +1,65 @@
+/**
+ * Dream commit (#1060): compute, then commit.
+ *
+ * A dream cycle is computed entirely in memory (spreading activation and
+ * insight generation never touch the database). Its results are then written
+ * here in ONE synchronous better-sqlite3 transaction: the activation levels,
+ * the insights and the final cycle row. There is no `await` inside the
+ * transaction, so no foreground write on the shared connection can join it,
+ * and no lock is held while asynchronous work runs. A cancelled, failed or
+ * interrupted dream commits nothing beyond its cycle row.
+ *
+ * Before #1060 the dream wrote its results one awaited statement at a time
+ * (and, with opt-in branching, inside a SAVEPOINT held across the whole
+ * asynchronous dream), so a discard or a shutdown mid-dream rolled back
+ * foreground writes that had already been acknowledged.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+import type { DreamCycle } from './types.js';
+import type { DreamInsight } from './insight-generator.js';
+/** Everything a dream cycle writes, computed before anything is written. */
+export interface ComputedDream {
+    cycle: DreamCycle;
+    /**
+     * Final activation level per concept node (clamped to [0, 1] on write),
+     * with the level the dream loaded. A node whose stored level no longer
+     * equals `loadedLevel` was written by someone else during the dream and is
+     * left alone. Omit `loadedLevel` to write unconditionally.
+     */
+    activations: ReadonlyArray<readonly [nodeId: string, level: number, loadedLevel?: number]>;
+    insights: readonly DreamInsight[];
+}
+export interface DreamCommitResult {
+    /** Wall-clock time the write transaction was open, in milliseconds. */
+    commitDurationMs: number;
+    /** Concept nodes updated (a node deleted meanwhile is skipped, not recreated). */
+    activationsWritten: number;
+    /** Activations skipped: the node vanished or a foreground write changed it. */
+    activationsSkipped: number;
+    insightsWritten: number;
+}
+/**
+ * Write a computed dream in one short synchronous transaction.
+ * Throws (and writes nothing) if any statement fails.
+ */
+export declare function commitDream(db: DatabaseType, dream: ComputedDream): DreamCommitResult;
+/**
+ * Margin added to the longest dream duration before a `running` cycle is
+ * treated as abandoned (covers graph loading and insight generation).
+ * DreamEngine.initialize() sweeps cycles older than
+ * max(config.maxDurationMs, 60 s) + this margin, 11 minutes by default.
+ * Library callers running longer dreams must raise maxDurationMs on every
+ * engine sharing the database (see DreamEngine.dream()).
+ */
+export declare const ABANDONED_CYCLE_GRACE_MS: number;
+/** Error recorded on a cycle the abandoned-cycle sweep marks interrupted. */
+export declare const ABANDONED_CYCLE_ERROR = "abandoned: process exited";
+/**
+ * Mark cycles a dead process left `running` as `interrupted` (#1060). Only a
+ * cycle that started more than `olderThanMs` ago is touched, so pass at least
+ * the longest dream duration plus ABANDONED_CYCLE_GRACE_MS: a cycle still
+ * running in another live process is then never marked. Rows are only
+ * updated, never deleted. Returns the number of cycles marked.
+ */
+export declare function markAbandonedCycles(db: DatabaseType, olderThanMs?: number, now?: number): number;
+//# sourceMappingURL=dream-commit.d.ts.map