agentic-qe 3.14.6 → 3.14.7

package/dist/integrations/vibium/client.js

@@ -7,6 +7,7 @@
  * @module integrations/vibium/client
  */
 import { randomUUID } from 'crypto';
+import { loadVibium, isVibiumReady, VIBIUM_SETUP } from './runtime.js';
 import { DEFAULT_VIBIUM_CONFIG } from './types.js';
 import { VibiumError, VibiumUnavailableError, VibiumTimeoutError, VibiumElementNotFoundError, VibiumConnectionError, VibiumNavigationError, VibiumScreenshotError, VibiumInteractionError, createVibiumError, } from './errors.js';
 import { toError } from '../../shared/error-utils.js';
@@ -24,7 +25,7 @@ async function getVibiumBrowser() {
         return vibiumBrowser;
     }
     try {
-        const vibium = await import('vibium');
+        const vibium = await loadVibium();
         vibiumBrowser = vibium.browser;
         vibiumAvailable = true;
         return vibiumBrowser;
@@ -112,6 +113,7 @@ export class VibiumClientImpl {
     _available = null;
     // Real Vibium browser instance
     vibeInstance = null;
+    browserInstance = null;
     /**
      * Create a new Vibium client
      *
@@ -133,7 +135,7 @@ export class VibiumClientImpl {
         try {
             // Check if Vibium package is available
             const browser = await getVibiumBrowser();
-            this._available = browser !== null;
+            this._available = browser !== null && isVibiumReady();
             return this._available;
         }
         catch {
@@ -157,7 +159,7 @@ export class VibiumClientImpl {
             if (isAvailable) {
                 this.lastHealthCheck = {
                     status: this.vibeInstance ? 'connected' : 'disconnected',
-                    version: '0.1.2', // From package.json
+                    // Runtime availability is checked against the installed payload.
                     browserType: this.config.browserType,
                     features: [
                         'browser-launch',
@@ -177,7 +179,7 @@ export class VibiumClientImpl {
                     status: 'unavailable',
                     features: ['fallback-only'],
                     lastChecked,
-                    error: 'Vibium package not available - install with: npm install vibium',
+                    error: `Vibium runtime or browser payload unavailable; run ${VIBIUM_SETUP}`,
                     sessionActive: false,
                 };
             }
@@ -209,13 +211,22 @@ export class VibiumClientImpl {
         const operation = async () => {
             const browser = await getVibiumBrowser();
             if (!browser) {
-                throw new VibiumUnavailableError('Vibium package not available. Install with: npm install vibium');
+                throw new VibiumUnavailableError(`Vibium runtime unavailable; run ${VIBIUM_SETUP}`);
             }
             // Launch REAL browser using Vibium
             const headless = options?.headless ?? this.config.headless;
-            this.vibeInstance = await browser.launch({
-                headless,
-            });
+            if (!isVibiumReady()) {
+                throw new VibiumUnavailableError(`Vibium browser payload unavailable; run ${VIBIUM_SETUP}`);
+            }
+            const instance = await browser.start({ headless });
+            try {
+                this.vibeInstance = await instance.page();
+                this.browserInstance = instance;
+            }
+            catch (error) {
+                await instance.stop();
+                throw error;
+            }
             const session = {
                 id: this.generateSessionId(),
                 browserType: this.config.browserType,
@@ -247,8 +258,9 @@ export class VibiumClientImpl {
         }
         const operation = async () => {
             if (this.vibeInstance) {
-                await this.vibeInstance.quit();
+                await this.browserInstance?.stop();
                 this.vibeInstance = null;
+                this.browserInstance = null;
             }
             this.currentSession = null;
         };
@@ -575,7 +587,7 @@ export class VibiumClientImpl {
         this.ensureSession();
         try {
             // Use real Vibium evaluate method
-            const result = await this.vibeInstance.evaluate(script);
+            const result = await this.vibeInstance.evaluate(`(async () => { ${script} })()`);
             return { success: true, value: result };
         }
         catch (error) {
@@ -608,13 +620,14 @@ export class VibiumClientImpl {
     async dispose() {
         if (this.vibeInstance) {
             try {
-                await this.vibeInstance.quit();
+                await this.browserInstance?.stop();
             }
             catch (error) {
                 // Non-critical: Vibium disposal errors
                 console.debug('[VibiumClient] Disposal error:', error instanceof Error ? error.message : error);
             }
             this.vibeInstance = null;
+            this.browserInstance = null;
         }
         this.currentSession = null;
         this._initialized = false;

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

@@ -0,0 +1,14 @@
+export declare const VIBIUM_SETUP = "aqe init --browser-engine (or npm install vibium@^26.8.21)";
+type Runtime = typeof import('vibium');
+/**
+ * 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
+ * CVE-2024-27980 fix), so run the npm CLI bundled next to node.exe instead.
+ * Falls back to plain `npm` when that layout is absent.
+ */
+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 {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/integrations/vibium/runtime.js

@@ -0,0 +1,94 @@
+/** 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';
+export const VIBIUM_SETUP = 'aqe init --browser-engine (or npm install vibium@^26.8.21)';
+const requireFromHere = createRequire(import.meta.url);
+/**
+ * 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
+ * CVE-2024-27980 fix), so run the npm CLI bundled next to node.exe instead.
+ * Falls back to plain `npm` when that layout is absent.
+ */
+export function npmInvocation(platform = process.platform, execPath = process.execPath, exists = existsSync) {
+    if (platform === 'win32') {
+        const npmCli = join(dirname(execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+        if (exists(npmCli))
+            return [execPath, [npmCli]];
+    }
+    return ['npm', []];
+}
+/** Never install or download anything while probing availability. */
+function resolveRuntime() {
+    try {
+        return requireFromHere.resolve('vibium');
+    }
+    catch {
+        try {
+            return createRequire(join(process.cwd(), 'package.json')).resolve('vibium');
+        }
+        catch { /* No project-local opt-in runtime. Try global setup below. */ }
+        // 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();
+        return requireFromHere.resolve(join(root, 'vibium'));
+    }
+}
+/**
+ * Accept the modern API from the namespace itself or from its `default`
+ * export. CJS interop and bundler createRequire shims expose the package
+ * object only as `default`, so checking the namespace alone rejects a
+ * correctly installed runtime.
+ */
+function selectBrowserApi(loaded) {
+    if (typeof loaded?.browser?.start === 'function')
+        return loaded;
+    if (typeof loaded?.default?.browser?.start === 'function')
+        return loaded.default;
+    return null;
+}
+export async function loadVibium() {
+    let loaded;
+    try {
+        loaded = await import('vibium');
+    }
+    catch (error) {
+        // Only a missing local package permits global resolution. A broken local
+        // installation must not be silently replaced by an unrelated runtime.
+        if (error.code !== 'ERR_MODULE_NOT_FOUND' &&
+            error.code !== 'MODULE_NOT_FOUND')
+            throw error;
+        let entry;
+        try {
+            entry = resolveRuntime();
+        }
+        catch (cause) {
+            throw new Error(`Vibium is not installed; run ${VIBIUM_SETUP}`, { cause });
+        }
+        loaded = requireFromHere(entry);
+    }
+    const runtime = selectBrowserApi(loaded);
+    if (!runtime) {
+        throw new Error('Unsupported Vibium API: the installed package exposes no browser.start() ' +
+            `(neither as a named nor a default export); run ${VIBIUM_SETUP}`);
+    }
+    return runtime;
+}
+/** Check the payload belonging to the resolved library, not a different PATH CLI. */
+export function isVibiumReady() {
+    try {
+        const cli = join(dirname(resolveRuntime()), '..', 'bin', 'cli.js');
+        execFileSync(process.execPath, [cli, 'is-installed'], {
+            timeout: 5000, stdio: 'ignore',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/kernel/pattern-fts-self-heal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * qe_patterns FTS5 self-heal (runs on every open, not gated on schema version)
+ *
+ * `qe_patterns_fts` is an FTS5 *external-content* table: it stores only the
+ * inverted index, and the three AFTER INSERT/UPDATE/DELETE triggers on
+ * qe_patterns are the ONLY thing keeping it in sync. Migration v9 creates them
+ * once (`currentVersion < 9`), so a database whose triggers were lost later
+ * (older code, a `.recover`, a copy/restore, a manual drop...) never heals:
+ * new patterns are invisible to keyword search and deleted ones linger as
+ * stale entries that skew BM25. Since hybrid FTS5+vector retrieval (#780/#796)
+ * keyword search is part of production ranking, so drift silently degrades
+ * retrieval and anything that locates a pattern through FTS.
+ *
+ * This module detects that state cheaply and repairs it idempotently:
+ *   1. qe_patterns exists but qe_patterns_fts doesn't  -> create the table
+ *   2. any sync trigger missing                         -> recreate it (shared DDL)
+ *   3. a sync trigger whose body differs from the shared DDL -> drop + recreate
+ *      (CREATE TRIGGER IF NOT EXISTS never replaces a same-named trigger)
+ *   4. any of the above OR index rowids != content rowids -> FTS5 'rebuild'
+ *
+ * Detection is read-only (counts + one anti-join on the docsize PK); the write
+ * transaction (BEGIN IMMEDIATE) is taken only when a repair is needed. It never
+ * throws: failures are logged and the caller continues (FTS search already
+ * degrades to vector-only). Read-only connections are skipped entirely.
+ *
+ * The 'rebuild' command reconstructs the index from the content table and
+ * never modifies qe_patterns rows.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+/** Names of the triggers that keep qe_patterns_fts in sync. */
+export declare const QE_PATTERNS_FTS_TRIGGERS: string[];
+export type PatternFtsHealStatus = 'healthy' | 'healed' | 'no-patterns' | 'readonly' | 'failed';
+export interface PatternFtsHealResult {
+    status: PatternFtsHealStatus;
+    /** True when qe_patterns_fts had to be created. */
+    createdTable: boolean;
+    /** Triggers that were missing and have been recreated. */
+    recreatedTriggers: string[];
+    /** Triggers whose body differed from the shared DDL and have been replaced. */
+    replacedTriggers: string[];
+    /** True when the FTS5 'rebuild' command ran. */
+    rebuilt: boolean;
+    /** qe_patterns row count observed before repair (-1 if unknown). */
+    patternsBefore: number;
+    /** Indexed document count before repair (-1 if unknown / no table). */
+    indexedBefore: number;
+    /** Indexed document count after repair (-1 if not repaired). */
+    indexedAfter: number;
+    error?: string;
+}
+export interface PatternFtsHealOptions {
+    /** Log sink for the single heal/failure line. Defaults to console.warn. */
+    log?: (message: string) => void;
+    /** Prefix for the log line, e.g. "[UnifiedMemory]". */
+    logPrefix?: string;
+}
+/**
+ * Ensure qe_patterns_fts exists, has its three sync triggers, and indexes
+ * exactly the rows of qe_patterns. Idempotent and silent when healthy; logs
+ * one line when it repairs something; never throws.
+ */
+export declare function ensurePatternFtsInSync(db: DatabaseType, options?: PatternFtsHealOptions): PatternFtsHealResult;
+//# sourceMappingURL=pattern-fts-self-heal.d.ts.map

package/dist/kernel/pattern-fts-self-heal.js

@@ -0,0 +1,193 @@
+/**
+ * qe_patterns FTS5 self-heal (runs on every open, not gated on schema version)
+ *
+ * `qe_patterns_fts` is an FTS5 *external-content* table: it stores only the
+ * inverted index, and the three AFTER INSERT/UPDATE/DELETE triggers on
+ * qe_patterns are the ONLY thing keeping it in sync. Migration v9 creates them
+ * once (`currentVersion < 9`), so a database whose triggers were lost later
+ * (older code, a `.recover`, a copy/restore, a manual drop...) never heals:
+ * new patterns are invisible to keyword search and deleted ones linger as
+ * stale entries that skew BM25. Since hybrid FTS5+vector retrieval (#780/#796)
+ * keyword search is part of production ranking, so drift silently degrades
+ * retrieval and anything that locates a pattern through FTS.
+ *
+ * This module detects that state cheaply and repairs it idempotently:
+ *   1. qe_patterns exists but qe_patterns_fts doesn't  -> create the table
+ *   2. any sync trigger missing                         -> recreate it (shared DDL)
+ *   3. a sync trigger whose body differs from the shared DDL -> drop + recreate
+ *      (CREATE TRIGGER IF NOT EXISTS never replaces a same-named trigger)
+ *   4. any of the above OR index rowids != content rowids -> FTS5 'rebuild'
+ *
+ * Detection is read-only (counts + one anti-join on the docsize PK); the write
+ * transaction (BEGIN IMMEDIATE) is taken only when a repair is needed. It never
+ * throws: failures are logged and the caller continues (FTS search already
+ * degrades to vector-only). Read-only connections are skipped entirely.
+ *
+ * The 'rebuild' command reconstructs the index from the content table and
+ * never modifies qe_patterns rows.
+ */
+import { toErrorMessage } from '../shared/error-utils.js';
+import { QE_PATTERNS_FTS_TABLE_DDL, QE_PATTERNS_FTS_TRIGGER_DDL, } from './unified-memory-schemas.js';
+/** Names of the triggers that keep qe_patterns_fts in sync. */
+export const QE_PATTERNS_FTS_TRIGGERS = Object.keys(QE_PATTERNS_FTS_TRIGGER_DDL);
+function objectExists(db, type, name) {
+    return db.prepare('SELECT 1 FROM sqlite_master WHERE type = ? AND name = ?').get(type, name) !== undefined;
+}
+/**
+ * Canonical form of a CREATE TRIGGER statement for comparison: sqlite_master
+ * stores the text as written minus IF NOT EXISTS, and older code paths used
+ * different indentation, so collapse whitespace and drop the clause/semicolon.
+ */
+function normalizeTriggerSql(sql) {
+    return sql
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^CREATE TRIGGER IF NOT EXISTS /i, 'CREATE TRIGGER ')
+        .replace(/ ?;$/, '')
+        .toLowerCase();
+}
+const CANONICAL_TRIGGER_SQL = Object.freeze(Object.fromEntries(Object.entries(QE_PATTERNS_FTS_TRIGGER_DDL).map(([name, ddl]) => [name, normalizeTriggerSql(ddl)])));
+function count(db, sql) {
+    const row = db.prepare(sql).get();
+    return row?.n ?? 0;
+}
+/**
+ * Read-only inspection. `qe_patterns_fts_docsize` holds exactly one row per
+ * indexed document (id = content rowid; columnsize defaults to on), so
+ * comparing it with qe_patterns detects both unindexed and stale entries
+ * without scanning the index itself. `SELECT count(*) FROM qe_patterns_fts`
+ * is NOT usable: for an external-content table it reads the content table.
+ */
+function inspect(db) {
+    const hasTable = objectExists(db, 'table', 'qe_patterns_fts');
+    const hasDocsize = hasTable && objectExists(db, 'table', 'qe_patterns_fts_docsize');
+    const missingTriggers = [];
+    const mismatchedTriggers = [];
+    const triggerSql = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'trigger' AND name = ?");
+    for (const name of QE_PATTERNS_FTS_TRIGGERS) {
+        const row = triggerSql.get(name);
+        if (row === undefined)
+            missingTriggers.push(name);
+        else if (normalizeTriggerSql(row.sql ?? '') !== CANONICAL_TRIGGER_SQL[name])
+            mismatchedTriggers.push(name);
+    }
+    const patterns = count(db, 'SELECT count(*) AS n FROM qe_patterns');
+    const indexed = hasDocsize ? count(db, 'SELECT count(*) AS n FROM qe_patterns_fts_docsize') : -1;
+    // Equal counts + every content rowid indexed => identical rowid sets (both
+    // sides are unique), so one anti-join over the docsize PK suffices.
+    const unindexed = hasDocsize && indexed === patterns
+        ? count(db, `SELECT count(*) AS n FROM qe_patterns p
+                 WHERE NOT EXISTS (SELECT 1 FROM qe_patterns_fts_docsize d WHERE d.id = p.rowid)`)
+        : 0;
+    return { hasTable, hasDocsize, missingTriggers, mismatchedTriggers, patterns, indexed, unindexed };
+}
+function needsRepair(s) {
+    if (!s.hasTable || s.missingTriggers.length > 0 || s.mismatchedTriggers.length > 0)
+        return true;
+    // Without a docsize table (non-default FTS options) drift can't be measured
+    // cheaply; trust the triggers rather than rebuilding on every open.
+    if (!s.hasDocsize)
+        return false;
+    return s.indexed !== s.patterns || s.unindexed > 0;
+}
+function isReadOnly(db) {
+    if (db.readonly)
+        return true;
+    try {
+        return Number(db.pragma('query_only', { simple: true })) === 1;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure qe_patterns_fts exists, has its three sync triggers, and indexes
+ * exactly the rows of qe_patterns. Idempotent and silent when healthy; logs
+ * one line when it repairs something; never throws.
+ */
+export function ensurePatternFtsInSync(db, options = {}) {
+    const log = options.log ?? ((m) => console.warn(m));
+    const prefix = options.logPrefix ?? '[PatternFTS]';
+    const result = {
+        status: 'healthy',
+        createdTable: false,
+        recreatedTriggers: [],
+        replacedTriggers: [],
+        rebuilt: false,
+        patternsBefore: -1,
+        indexedBefore: -1,
+        indexedAfter: -1,
+    };
+    try {
+        if (!objectExists(db, 'table', 'qe_patterns')) {
+            result.status = 'no-patterns';
+            return result;
+        }
+        if (isReadOnly(db)) {
+            result.status = 'readonly';
+            return result;
+        }
+        const before = inspect(db);
+        result.patternsBefore = before.patterns;
+        result.indexedBefore = before.indexed;
+        if (!needsRepair(before))
+            return result;
+        // Re-inspect inside BEGIN IMMEDIATE so a concurrent opener that already
+        // healed (or is mid-write) is observed under the write lock. Results are
+        // only published after COMMIT succeeds: a failed commit rolls everything
+        // back and must not be reported as a repair.
+        const repaired = db.transaction(() => {
+            const s = inspect(db);
+            if (!needsRepair(s))
+                return null;
+            if (!s.hasTable)
+                db.exec(QE_PATTERNS_FTS_TABLE_DDL);
+            for (const name of s.missingTriggers)
+                db.exec(QE_PATTERNS_FTS_TRIGGER_DDL[name]);
+            for (const name of s.mismatchedTriggers) {
+                db.exec(`DROP TRIGGER IF EXISTS ${name}`);
+                db.exec(QE_PATTERNS_FTS_TRIGGER_DDL[name]);
+            }
+            // Rebuild from the content table: clears stale entries and indexes rows
+            // inserted/updated while triggers were absent. Never touches qe_patterns.
+            db.exec("INSERT INTO qe_patterns_fts(qe_patterns_fts) VALUES('rebuild')");
+            return { s, indexedAfter: count(db, 'SELECT count(*) AS n FROM qe_patterns_fts_docsize') };
+        }).immediate();
+        if (repaired) {
+            const { s } = repaired;
+            result.createdTable = !s.hasTable;
+            result.recreatedTriggers = [...s.missingTriggers];
+            result.replacedTriggers = [...s.mismatchedTriggers];
+            result.patternsBefore = s.patterns;
+            result.indexedBefore = s.indexed;
+            result.indexedAfter = repaired.indexedAfter;
+            result.rebuilt = true;
+        }
+        if (result.rebuilt) {
+            result.status = 'healed';
+            const parts = [];
+            if (result.createdTable)
+                parts.push('created qe_patterns_fts');
+            if (result.recreatedTriggers.length > 0) {
+                parts.push(`recreated triggers [${result.recreatedTriggers.join(', ')}]`);
+            }
+            if (result.replacedTriggers.length > 0) {
+                parts.push(`replaced triggers [${result.replacedTriggers.join(', ')}]`);
+            }
+            const indexedBefore = result.indexedBefore < 0 ? 'n/a' : String(result.indexedBefore);
+            parts.push(`rebuilt index (indexed ${indexedBefore} -> ${result.indexedAfter}, qe_patterns ${result.patternsBefore})`);
+            log(`${prefix} Healed qe_patterns FTS5 index: ${parts.join('; ')}`);
+        }
+        return result;
+    }
+    catch (error) {
+        result.status = 'failed';
+        result.error = toErrorMessage(error);
+        try {
+            log(`${prefix} qe_patterns FTS5 self-heal skipped: ${result.error} (keyword search may be degraded; vector search unaffected)`);
+        }
+        catch { /* logging must never break open */ }
+        return result;
+    }
+}
+//# sourceMappingURL=pattern-fts-self-heal.js.map

package/dist/kernel/process-lifecycle.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Agentic QE v3 - Process lifecycle ownership (#801)
+ *
+ * A long-running entry point (the MCP server) owns process shutdown: before it
+ * exits it must drain in-flight work and release native handles. The shared
+ * patterns RVF adapter, for example, holds a `patterns.rvf.lock` marker that
+ * only its own close() removes.
+ *
+ * Module-level signal handlers elsewhere (the kernel stores, the CLI wrapper)
+ * used to call `process.exit(0)` synchronously. Node runs signal listeners one
+ * after another in the same tick, so that exit pre-empted the owner's async
+ * graceful shutdown and leaked the marker. Those handlers now route the
+ * request to the claimed owner and do not exit themselves.
+ *
+ * With no owner claimed (every non-MCP CLI command), nothing changes and
+ * callers keep their own exit behaviour.
+ *
+ * The owner lives on `globalThis` under a registry symbol because `aqe mcp`
+ * loads the MCP bundle into the CLI bundle's process. Each bundle has its own
+ * copy of this module, and both copies must see the same owner.
+ */
+export interface ProcessLifecycleOwner {
+    /** Diagnostic name, e.g. `mcp`. */
+    readonly name: string;
+    /**
+     * Start the owner's graceful shutdown. Must be idempotent, must not throw,
+     * and must eventually exit the process (e.g. guarded by a watchdog). Before
+     * exiting, on every path, it must call `closeRegisteredStores()`.
+     */
+    shutdown(reason: string): void;
+}
+/**
+ * Register a synchronous, idempotent close for a process-wide store (the
+ * kernel's unified memory/persistence singletons). A claimed owner closes
+ * every registered store at the end of its shutdown, so stores are closed on
+ * every termination path, not only the signal ones. Returns an unregister
+ * function. Shared across bundle copies through the registry symbol.
+ */
+export declare function registerStoreCloser(close: () => void): () => void;
+/**
+ * Close every registered store, most recently registered first (a facade is
+ * registered after the store it wraps, so it closes first). Synchronous so it
+ * also works from a process 'exit' listener; never throws. Closers must be
+ * idempotent: this may run from both the shutdown and an exit backstop.
+ */
+export declare function closeRegisteredStores(): void;
+/** Make `owner` responsible for every graceful shutdown in this process. */
+export declare function claimProcessLifecycle(owner: ProcessLifecycleOwner): void;
+/** Remove the current owner (only if it is still `owner`, when given). Test seam. */
+export declare function releaseProcessLifecycle(owner?: ProcessLifecycleOwner): void;
+export declare function getProcessLifecycleOwner(): ProcessLifecycleOwner | undefined;
+/**
+ * Hand a termination request to the claimed owner.
+ *
+ * Returns true when an owner accepted it: the caller must then NOT exit the
+ * process itself. Returns false when no owner is claimed: the caller keeps its
+ * own behaviour.
+ */
+export declare function requestOwnedShutdown(reason: string): boolean;
+//# sourceMappingURL=process-lifecycle.d.ts.map

package/dist/kernel/process-lifecycle.js

@@ -0,0 +1,91 @@
+/**
+ * Agentic QE v3 - Process lifecycle ownership (#801)
+ *
+ * A long-running entry point (the MCP server) owns process shutdown: before it
+ * exits it must drain in-flight work and release native handles. The shared
+ * patterns RVF adapter, for example, holds a `patterns.rvf.lock` marker that
+ * only its own close() removes.
+ *
+ * Module-level signal handlers elsewhere (the kernel stores, the CLI wrapper)
+ * used to call `process.exit(0)` synchronously. Node runs signal listeners one
+ * after another in the same tick, so that exit pre-empted the owner's async
+ * graceful shutdown and leaked the marker. Those handlers now route the
+ * request to the claimed owner and do not exit themselves.
+ *
+ * With no owner claimed (every non-MCP CLI command), nothing changes and
+ * callers keep their own exit behaviour.
+ *
+ * The owner lives on `globalThis` under a registry symbol because `aqe mcp`
+ * loads the MCP bundle into the CLI bundle's process. Each bundle has its own
+ * copy of this module, and both copies must see the same owner.
+ */
+const OWNER_KEY = Symbol.for('agentic-qe.process-lifecycle-owner');
+const CLOSERS_KEY = Symbol.for('agentic-qe.process-lifecycle-store-closers');
+function closers() {
+    const g = globalThis;
+    return (g[CLOSERS_KEY] ??= []);
+}
+/**
+ * Register a synchronous, idempotent close for a process-wide store (the
+ * kernel's unified memory/persistence singletons). A claimed owner closes
+ * every registered store at the end of its shutdown, so stores are closed on
+ * every termination path, not only the signal ones. Returns an unregister
+ * function. Shared across bundle copies through the registry symbol.
+ */
+export function registerStoreCloser(close) {
+    closers().push(close);
+    return () => {
+        const list = closers();
+        const at = list.indexOf(close);
+        if (at >= 0)
+            list.splice(at, 1);
+    };
+}
+/**
+ * Close every registered store, most recently registered first (a facade is
+ * registered after the store it wraps, so it closes first). Synchronous so it
+ * also works from a process 'exit' listener; never throws. Closers must be
+ * idempotent: this may run from both the shutdown and an exit backstop.
+ */
+export function closeRegisteredStores() {
+    for (const close of [...closers()].reverse()) {
+        try {
+            close();
+        }
+        catch { /* best effort: keep closing the rest */ }
+    }
+}
+/** Make `owner` responsible for every graceful shutdown in this process. */
+export function claimProcessLifecycle(owner) {
+    globalThis[OWNER_KEY] = owner;
+}
+/** Remove the current owner (only if it is still `owner`, when given). Test seam. */
+export function releaseProcessLifecycle(owner) {
+    const g = globalThis;
+    if (!owner || g[OWNER_KEY] === owner)
+        delete g[OWNER_KEY];
+}
+export function getProcessLifecycleOwner() {
+    return globalThis[OWNER_KEY];
+}
+/**
+ * Hand a termination request to the claimed owner.
+ *
+ * Returns true when an owner accepted it: the caller must then NOT exit the
+ * process itself. Returns false when no owner is claimed: the caller keeps its
+ * own behaviour.
+ */
+export function requestOwnedShutdown(reason) {
+    const owner = getProcessLifecycleOwner();
+    if (!owner)
+        return false;
+    try {
+        owner.shutdown(reason);
+        return true;
+    }
+    catch {
+        // A broken owner must not leave the process running: let the caller exit.
+        return false;
+    }
+}
+//# sourceMappingURL=process-lifecycle.js.map