@cleocode/core 2026.7.2 → 2026.8.2

package/dist/store/dual-scope-db.js

@@ -51,14 +51,14 @@
  */
 import { existsSync, mkdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { getLogger } from '../logger.js';
 import { getCleoHome, resolveCleoDir } from '../paths.js';
 import { getRecordedExodusAbort } from './exodus/abort-events.js';
 import { migrateWithRetry, reconcileJournal } from './migration-manager.js';
 import { resolveConsolidatedJournalSiblings, resolveCorePackageMigrationsFolder, } from './resolve-migrations-folder.js';
 import { applyPerfPragmas } from './sqlite-pragmas.js';
-import { activeScope, activeScopeDbPath, withColdOpenLease, withWriterLease, } from './writer-lease.js';
+import { makeWriterLeaseIdentity, registerDbIdentity, resolveDbIdentity, withColdOpenLease, withWriterLease, } from './writer-lease.js';
 /**
  * Thrown by {@link assertWriteDurable} when a MUTATING caller is about to write
  * through a {@link DualScopeDbHandle} whose first-open exodus auto-migration
@@ -204,24 +204,6 @@ function getDatabaseSyncCtor() {
     }
     return _DatabaseSyncCtor;
 }
-// ── Schema loading ───────────────────────────────────────────────────────────
-// Dynamic imports for schema barrels. Loaded once per scope and cached.
-// We use dynamic import() to avoid loading both schemas at module-init time —
-// only the requested scope's schema is loaded.
-let _projectSchema = null;
-let _globalSchema = null;
-async function loadProjectSchema() {
-    if (_projectSchema === null) {
-        _projectSchema = await import('./schema/cleo-project/index.js');
-    }
-    return _projectSchema;
-}
-async function loadGlobalSchema() {
-    if (_globalSchema === null) {
-        _globalSchema = await import('./schema/cleo-global/index.js');
-    }
-    return _globalSchema;
-}
 // ── Existence table for migration reconciliation ──────────────────────────────
 /**
  * The "existence table" used by {@link reconcileJournal} to detect whether
@@ -312,36 +294,58 @@ async function openDedicatedDualScopeDb(scope, dbPath, log) {
     }
     const DatabaseSyncCtor = getDatabaseSyncCtor();
     const nativeDb = new DatabaseSyncCtor(dbPath, { allowExtension: true });
-    // T11829: bound per-connection memory for one-shot/CLI opens (full SSoT for daemon).
-    applyPerfPragmas(nativeDb, memoryBoundedPragmaOverrides());
-    const schema = scope === 'project' ? await loadProjectSchema() : await loadGlobalSchema();
-    const drizzle = getDrizzle();
-    // biome-ignore lint/suspicious/noExplicitAny: schema type is scope-specific; typed via DualScopeDbHandle<TScope>
-    const db = drizzle({ client: nativeDb, schema });
-    const migrationsFolder = resolveCorePackageMigrationsFolder(migrationsSetName(scope));
-    // T11829: pass the OTHER lineages that share this scope's consolidated cleo.db
-    // journal so their rows are never deleted as cross-lineage orphans. Both scopes
-    // are consolidated single-file substrates with multiple coexisting lineages
-    // (project: tasks/cleo-project/nexus/conduit/brain; global:
-    // cleo-global/agent-registry/…). Over-inclusion across scopes is safe — a
-    // sibling hash absent from this file's journal contributes nothing.
-    reconcileJournal(nativeDb, migrationsFolder, existenceTable(scope), `dual-scope-db[${scope}]`, resolveConsolidatedJournalSiblings(migrationsSetName(scope)));
-    migrateWithRetry(db, migrationsFolder, nativeDb, existenceTable(scope), `dual-scope-db[${scope}]`);
-    log.debug({ scope, dbPath }, 'DEDICATED dual-scope cleo.db ready (T11782 FIX D)');
-    return {
-        db,
-        scope,
-        dbPath,
-        close() {
-            // Dedicated handles are never cached — close only the native connection.
-            try {
-                nativeDb.close();
-            }
-            catch {
-                // Idempotent — ignore double-close errors.
-            }
-        },
-    };
+    // Every operation after construction is wrapped so any exception —
+    // pragmas, Drizzle wrapping, migration-folder resolution, lease, or
+    // migration — closes the native handle before rethrow.
+    try {
+        // T11829: bound per-connection memory for one-shot/CLI opens (full SSoT for daemon).
+        applyPerfPragmas(nativeDb, memoryBoundedPragmaOverrides());
+        const drizzle = getDrizzle();
+        // biome-ignore lint/suspicious/noExplicitAny: dual-scope handle is untyped at construction; typed via DualScopeDbHandle<TScope>
+        const db = drizzle({ client: nativeDb });
+        const migrationsFolder = resolveCorePackageMigrationsFolder(migrationsSetName(scope));
+        // ── Cold-open lease (F4 · T12036) ──────────────────────────────────────
+        // Dedicated opens also serialize their cold-open migrations through the same
+        // writer-lease so they never race on the `__drizzle_migrations` journal
+        // even when two dedicated opens of a fresh file are concurrent.
+        const handle = await withColdOpenLease(scope, nativeDb, async () => {
+            reconcileJournal(nativeDb, migrationsFolder, existenceTable(scope), `dual-scope-db[${scope}]`, resolveConsolidatedJournalSiblings(migrationsSetName(scope)));
+            migrateWithRetry(db, migrationsFolder, nativeDb, existenceTable(scope), `dual-scope-db[${scope}]`);
+            log.debug({ scope, dbPath }, 'DEDICATED dual-scope cleo.db ready (T11782 FIX D)');
+            const identity = makeWriterLeaseIdentity(scope, dbPath);
+            registerDbIdentity(db, identity);
+            return {
+                db,
+                scope,
+                dbPath,
+                identity,
+                get isOpen() {
+                    return nativeDb.isOpen;
+                },
+                close() {
+                    // Dedicated handles are never cached — close only the native connection.
+                    try {
+                        nativeDb.close();
+                    }
+                    catch {
+                        // Idempotent — ignore double-close errors.
+                    }
+                },
+            };
+        });
+        return handle;
+    }
+    catch (err) {
+        // Close the native handle on any failure after construction to avoid
+        // leaking a file descriptor. The primary error is rethrown unchanged.
+        try {
+            nativeDb.close();
+        }
+        catch {
+            // Already closed or never opened — safe to ignore.
+        }
+        throw err;
+    }
 }
 export async function openDualScopeDbAtPath(scope, dbPath, 
 /**
@@ -353,7 +357,10 @@ export async function openDualScopeDbAtPath(scope, dbPath,
  */
 exodusCwd, options) {
     const dedicated = options?.dedicated === true;
-    const key = cacheKey(scope, dbPath);
+    // Normalize the path before keying so equivalent spellings share one
+    // cache entry — the chokepoint key mirrors the runtime's path.resolve.
+    const normalizedPath = resolve(dbPath);
+    const key = cacheKey(scope, normalizedPath);
     // A DEDICATED open (T11782 · FIX D) bypasses the singleton cache entirely: it
     // opens a SECOND SQLite connection to the same file (WAL allows concurrent
     // connections) so the exodus migrate engine can copy + (on abort) truncate on
@@ -370,206 +377,29 @@ exodusCwd, options) {
             if (existing.initPromise) {
                 return existing.initPromise;
             }
-            return existing.handle;
+            if (existing.handle && existing.nativeDb?.isOpen) {
+                return existing.handle;
+            }
+            _cache.delete(key);
         }
     }
     const log = getLogger('dual-scope-db');
     if (dedicated) {
-        return openDedicatedDualScopeDb(scope, dbPath, log);
+        return openDedicatedDualScopeDb(scope, normalizedPath, log);
     }
     // Create a placeholder entry so concurrent callers wait for the same init.
-    const initPromise = (async () => {
-        log.debug({ scope, dbPath }, 'opening dual-scope cleo.db');
-        // Ensure the directory exists before opening.
-        const dir = dirname(dbPath);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        // Open the native SQLite handle.
-        //
-        // `allowExtension: true` permits — but does NOT load — SQLite loadable
-        // extensions. The brain domain (E6-L2 · T11522) loads the `sqlite-vec`
-        // extension on this shared handle for vector similarity search; node:sqlite
-        // requires the flag at construction time (it cannot be toggled afterwards
-        // via `enableLoadExtension`). Enabling the flag is harmless for every other
-        // domain — no extension is loaded automatically, and the cache stays
-        // single-keyed regardless of which domain opens the handle first.
-        const DatabaseSyncCtor = getDatabaseSyncCtor();
-        const nativeDb = new DatabaseSyncCtor(dbPath, { allowExtension: true });
-        // Apply canonical pragma set (specs/sqlite-pragmas.json SSoT), bounding
-        // per-connection memory for one-shot/CLI opens (full SSoT for daemon) — T11829.
-        applyPerfPragmas(nativeDb, memoryBoundedPragmaOverrides());
-        // Load the schema barrel for this scope.
-        const schema = scope === 'project' ? await loadProjectSchema() : await loadGlobalSchema();
-        // Create the Drizzle ORM wrapper.
-        // Drizzle v1 RC3 node-sqlite API: pass { client, schema } as a single config object.
-        const drizzle = getDrizzle();
-        // biome-ignore lint/suspicious/noExplicitAny: schema type is scope-specific; typed via DualScopeDbHandle<TScope>
-        const db = drizzle({ client: nativeDb, schema });
-        // Resolve the migrations folder for this scope.
-        const migrationsFolder = resolveCorePackageMigrationsFolder(migrationsSetName(scope));
-        // ── Seam 0 — cold-open critical section (THE T5158 HEAL · T11627 ST-3) ────
-        // Lease the migrate/reconcile cold-open write-txn against the just-opened
-        // native handle so EXACTLY ONE process per scope runs it while concurrent
-        // cold-open peers BEGIN IMMEDIATE-queue and then observe a ready DB. This heals
-        // the T5158 `E_NOT_INITIALIZED` / `E_INTERNAL` corruption (concurrent cold-open
-        // migrate write-txns racing the consolidated cleo.db's single shared
-        // `__drizzle_migrations` journal) WITH the supervisor daemon disabled (`local`
-        // mode default). `off` mode is a pass-through → byte-identical to pre-lease
-        // behaviour (busy_timeout=30000 still serializes the write-txn).
-        // `withColdOpenLease` also records the scope in the Seam-1 active-scope registry
-        // so chokepoint write primitives lease correctly.
-        //
-        // The lease wraps ONLY reconcileJournal + migrateWithRetry — the precise write-
-        // txn that races in T5158. The exodus-on-open hook runs AFTER the lease releases
-        // (below): it owns its OWN single-flight lock + dedicated migrate connections,
-        // and `runExodusMigrate` CLOSES + re-opens the scope handles, which would
-        // close the very handle the lease row lives on mid-section. Releasing first is
-        // both correct (exodus is already serialized) and necessary (no close-under-lease).
-        const handle = await withColdOpenLease(scope, nativeDb, async () => {
-            // Reconcile the migration journal (handles WAL/journal divergence across
-            // SQLite version upgrades — same pattern as sqlite.ts / memory-sqlite.ts).
-            // T11829: pass the OTHER lineages that share this scope's consolidated cleo.db
-            // journal so their rows are not deleted as cross-lineage orphans (the confirmed
-            // OOM root cause: each lineage previously deleted the others' rows so the shared
-            // journal never converged).
-            reconcileJournal(nativeDb, migrationsFolder, existenceTable(scope), `dual-scope-db[${scope}]`, resolveConsolidatedJournalSiblings(migrationsSetName(scope)));
-            // Run any pending migrations.
-            migrateWithRetry(db, migrationsFolder, nativeDb, existenceTable(scope), `dual-scope-db[${scope}]`);
-            log.debug({ scope, dbPath }, 'dual-scope cleo.db ready');
-            const built = {
-                db,
-                scope,
-                dbPath,
-                close() {
-                    _cache.delete(key);
-                    try {
-                        nativeDb.close();
-                    }
-                    catch {
-                        // Idempotent — ignore double-close errors.
-                    }
-                },
-            };
-            // Update the cache entry to mark init complete.
-            const entry = _cache.get(key);
-            if (entry) {
-                entry.initPromise = null;
-                entry.handle = built;
-            }
-            return built;
-        }, 
-        // Record this open's resolved dbPath in the Seam-1 registry so the chokepoint
-        // write primitives lease their row in THIS file — not the cwd-default — when
-        // more than one project's cleo.db is open in this process (T11627 Finding 1).
-        { dbPath });
-        // ── Exodus-on-open (E6 · T11553) — runs AFTER the cold-open lease releases ──
-        // Data-continuity safety net: on a canonical open where the consolidated
-        // cleo.db is empty but the legacy fleet (tasks.db/brain.db/…) has rows for
-        // THIS scope, lazily auto-migrate ONCE — gated by a parity verify, serialised
-        // by a single-flight lock, rolled back to empty on parity failure (legacy
-        // kept). Re-entrancy/concurrency are handled inside the hook. Lazy `import()`
-        // breaks the cycle (exodus/migrate.ts imports openDualScopeDb from here).
-        //
-        // NOTE: `runExodusMigrate` CLOSES + evicts the dual-scope handles it opened
-        // when it finishes, so after a `migrated`/`aborted` outcome the `handle`
-        // built above (and its `nativeDb`) is CLOSED. We therefore re-open this scope
-        // fresh (cache-miss, NOT armed — no `exodusCwd`) and return the new live
-        // handle. That re-open flows through the cold-open lease again on a FRESH handle
-        // (cheap claim/release — the DB is now migrated), with no contention against the
-        // already-released outer lease.
-        //
-        // Armed ONLY when `exodusCwd` was threaded through the canonical
-        // `openDualScopeDb` AND `dbPath` is the canonical path for that scope+cwd —
-        // never for explicit-path opens (test fixtures / legacy-path domains).
-        if (exodusCwd !== undefined && dbPath === resolveDualScopeDbPath(scope, exodusCwd)) {
-            // ── T12001 (Epic T11992) — db-heavy admission for the exodus auto-migrate ──
-            // The on-open exodus (reconcile + parity verify + migrate) is a heavy DB op;
-            // letting it co-schedule with builds/tests/agents is a historical OOM vector.
-            // Admit it through the governor's `db-heavy` class (machine-wide serialized;
-            // deferred under memory backoff). On a denial we SKIP the migration THIS open
-            // (kill-switch precedent CLEO_DISABLE_EXODUS_ON_OPEN) — NEVER block or defer
-            // the interactive command (interactive-cli is never gated) — and it re-runs
-            // idempotently on a calmer open. Fail-open: ANY governor error proceeds
-            // un-gated, byte-identical to pre-T12001 behaviour.
-            let releaseDbHeavy = null;
-            let dbHeavyDeferred = false;
-            try {
-                const { governor } = await import('../resources/governor.js');
-                const admit = await governor.tryAcquire('db-heavy');
-                if (admit.deferred) {
-                    dbHeavyDeferred = true;
-                }
-                else {
-                    releaseDbHeavy = admit.release;
-                }
-            }
-            catch {
-                // Governor unavailable — fail open (proceed un-gated).
-            }
-            if (dbHeavyDeferred) {
-                log.debug({ scope, dbPath }, 'exodus-on-open skipped this open — db-heavy deferred under memory pressure ' +
-                    '(re-runs idempotently on a calmer open)');
-                return handle;
-            }
-            try {
-                const { maybeRunExodusOnOpen } = await import('./exodus/on-open.js');
-                const result = await maybeRunExodusOnOpen(scope, dbPath, nativeDb, exodusCwd);
-                if (result.outcome === 'migrated' || result.outcome === 'aborted') {
-                    // The migrate engine closed our handle — re-open fresh (un-armed) so the
-                    // caller receives a valid, live handle bound to the now-(de)populated DB.
-                    const reopened = scope === 'project'
-                        ? await openDualScopeDbAtPath('project', dbPath)
-                        : await openDualScopeDbAtPath('global', dbPath);
-                    if (result.outcome === 'aborted') {
-                        // T11828 (DHQ-059): the data-continuity gate aborted — the consolidated
-                        // DB is empty + consistent, legacy kept as source. Surface this to a
-                        // MUTATING caller (read-only callers ignore it) by (a) stamping a
-                        // structured marker on the returned handle and (b) broadcasting a typed
-                        // event. The non-zero error itself is raised on the write path via
-                        // `assertWriteDurable(handle)` — NOT here, so read opens never throw.
-                        const abort = {
-                            scope,
-                            dbPath,
-                            reason: result.reason,
-                            at: Date.now(),
-                        };
-                        log.warn({ scope, reason: result.reason }, 'exodus-on-open aborted; consolidated cleo.db left empty, legacy kept as source — ' +
-                            'mutating callers must check handle.exodusAbort / call assertWriteDurable (T11828)');
-                        const { emitExodusAbort } = await import('./exodus/abort-events.js');
-                        emitExodusAbort(abort);
-                        return { ...reopened, exodusAbort: abort };
-                    }
-                    // A subsequent SUCCESSFUL migration resolves any prior abort recorded
-                    // for this scope, so writes are no longer rejected (T11828).
-                    const { clearExodusAborts } = await import('./exodus/abort-events.js');
-                    clearExodusAborts(scope);
-                    return reopened;
-                }
-            }
-            catch (err) {
-                // Best-effort safety net: a hook failure must not make the DB
-                // unopenable. Warn and re-open fresh; `cleo exodus migrate` remains the
-                // manual path. (The handle may have been closed mid-migrate.)
-                log.warn({ err, scope }, 'exodus-on-open hook failed (non-fatal); re-opening consolidated handle');
-                return scope === 'project'
-                    ? openDualScopeDbAtPath('project', dbPath)
-                    : openDualScopeDbAtPath('global', dbPath);
-            }
-            finally {
-                // Release the db-heavy slot on EVERY exit path (early returns above run
-                // `finally` first). Idempotent; release errors are swallowed.
-                if (releaseDbHeavy)
-                    await releaseDbHeavy().catch(() => { });
-            }
-        }
-        return handle;
-    })();
-    // Store a placeholder with the in-flight promise so concurrent callers wait.
+    // MUST run BEFORE the async IIFE is defined: the IIFE starts executing
+    // synchronously, and the cold-open callback inside withColdOpenLease runs
+    // synchronously before the outer IIFE yields — if the placeholder entry
+    // doesn't exist yet, the callback cannot find and update it (T12035).
+    let initResolve = null;
+    let initReject = null;
+    const initPromise = new Promise((resolve, reject) => {
+        initResolve = resolve;
+        initReject = reject;
+    });
     _cache.set(key, {
-        // biome-ignore lint/suspicious/noExplicitAny: placeholder until initPromise resolves
         handle: null,
-        // biome-ignore lint/suspicious/noExplicitAny: nativeDb not available yet
         nativeDb: null,
         initPromise,
     });
@@ -588,6 +418,218 @@ exodusCwd, options) {
             _cache.delete(key);
         }
     });
+    // Start the actual init work. The IIFE is a fire-and-forget callback that
+    // resolves/rejects the externally-created initPromise. Separating promise
+    // creation from the async IIFE ensures the cache placeholder exists before
+    // any synchronous work runs inside withColdOpenLease's fn callback (T12035).
+    (async () => {
+        try {
+            log.debug({ scope, dbPath: normalizedPath }, 'opening dual-scope cleo.db');
+            // Ensure the directory exists before opening.
+            const dir = dirname(normalizedPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            // Open the native SQLite handle.
+            //
+            // `allowExtension: true` permits — but does NOT load — SQLite loadable
+            // extensions. The brain domain (E6-L2 · T11522) loads the `sqlite-vec`
+            // extension on this shared handle for vector similarity search; node:sqlite
+            // requires the flag at construction time (it cannot be toggled afterwards
+            // via `enableLoadExtension`). Enabling the flag is harmless for every other
+            // domain — no extension is loaded automatically, and the cache stays
+            // single-keyed regardless of which domain opens the handle first.
+            const DatabaseSyncCtor = getDatabaseSyncCtor();
+            const nativeDb = new DatabaseSyncCtor(normalizedPath, { allowExtension: true });
+            // Apply canonical pragma set (specs/sqlite-pragmas.json SSoT), bounding
+            // per-connection memory for one-shot/CLI opens (full SSoT for daemon) — T11829.
+            applyPerfPragmas(nativeDb, memoryBoundedPragmaOverrides());
+            // Create the Drizzle ORM wrapper.
+            const drizzle = getDrizzle();
+            // biome-ignore lint/suspicious/noExplicitAny: dual-scope handle is untyped at construction; typed via DualScopeDbHandle<TScope>
+            const db = drizzle({ client: nativeDb });
+            // Resolve the migrations folder for this scope.
+            const migrationsFolder = resolveCorePackageMigrationsFolder(migrationsSetName(scope));
+            // ── Seam 0 — cold-open critical section (THE T5158 HEAL · T11627 ST-3) ────
+            // Lease the migrate/reconcile cold-open write-txn against the just-opened
+            // native handle so EXACTLY ONE process per scope runs it while concurrent
+            // cold-open peers BEGIN IMMEDIATE-queue and then observe a ready DB. This heals
+            // the T5158 `E_NOT_INITIALIZED` / `E_INTERNAL` corruption (concurrent cold-open
+            // migrate write-txns racing the consolidated cleo.db's single shared
+            // `__drizzle_migrations` journal) WITH the supervisor daemon disabled (`local`
+            // mode default). `off` mode is a pass-through → byte-identical to pre-lease
+            // behaviour (busy_timeout=30000 still serializes the write-txn).
+            // The identity is bound to the drizzle DB handle via
+            // registerDbIdentity during construction — the chokepoint write
+            // primitives resolve it from the exact handle binding (T12042), no
+            // longer from a process-global active-scope registry.
+            //
+            // The lease wraps ONLY reconcileJournal + migrateWithRetry — the precise write-
+            // txn that races in T5158. The exodus-on-open hook runs AFTER the lease releases
+            // (below): it owns its OWN single-flight lock + dedicated migrate connections,
+            // and `runExodusMigrate` CLOSES + re-opens the scope handles, which would
+            // close the very handle the lease row lives on mid-section. Releasing first is
+            // both correct (exodus is already serialized) and necessary (no close-under-lease).
+            const handle = await withColdOpenLease(scope, nativeDb, async () => {
+                // Reconcile the migration journal (handles WAL/journal divergence across
+                // SQLite version upgrades — same pattern as sqlite.ts / memory-sqlite.ts).
+                // T11829: pass the OTHER lineages that share this scope's consolidated cleo.db
+                // journal so their rows are not deleted as cross-lineage orphans (the confirmed
+                // OOM root cause: each lineage previously deleted the others' rows so the shared
+                // journal never converged).
+                reconcileJournal(nativeDb, migrationsFolder, existenceTable(scope), `dual-scope-db[${scope}]`, resolveConsolidatedJournalSiblings(migrationsSetName(scope)));
+                // Run any pending migrations.
+                migrateWithRetry(db, migrationsFolder, nativeDb, existenceTable(scope), `dual-scope-db[${scope}]`);
+                log.debug({ scope, dbPath: normalizedPath }, 'dual-scope cleo.db ready');
+                const identity = makeWriterLeaseIdentity(scope, normalizedPath);
+                registerDbIdentity(db, identity);
+                const built = {
+                    db,
+                    scope,
+                    dbPath: normalizedPath,
+                    identity,
+                    get isOpen() {
+                        return nativeDb.isOpen;
+                    },
+                    close() {
+                        // Identity-guarded deletion: only evict from the singleton cache
+                        // when the current entry still references THIS exact handle. A stale
+                        // store close after a replacement was opened leaves the replacement
+                        // intact. The native connection is always closed regardless.
+                        const entry = _cache.get(key);
+                        if (entry?.handle === built) {
+                            _cache.delete(key);
+                        }
+                        try {
+                            nativeDb.close();
+                        }
+                        catch {
+                            // Idempotent — ignore double-close errors.
+                        }
+                    },
+                };
+                // Update the cache entry to mark init complete.
+                const entry = _cache.get(key);
+                if (entry) {
+                    entry.initPromise = null;
+                    entry.handle = built;
+                    entry.nativeDb = nativeDb;
+                }
+                return built;
+            });
+            // ── Exodus-on-open (E6 · T11553) — runs AFTER the cold-open lease releases ──
+            // Data-continuity safety net: on a canonical open where the consolidated
+            // cleo.db is empty but the legacy fleet (tasks.db/brain.db/…) has rows for
+            // THIS scope, lazily auto-migrate ONCE — gated by a parity verify, serialised
+            // by a single-flight lock, rolled back to empty on parity failure (legacy
+            // kept). Re-entrancy/concurrency are handled inside the hook. Lazy `import()`
+            // breaks the cycle (exodus/migrate.ts imports openDualScopeDb from here).
+            //
+            // NOTE: `runExodusMigrate` opens DEDICATED connections (not cached).
+            // When the migration finishes those dedicated handles close only their own
+            // `DatabaseSync` — they never touch the singleton `_cache`. After a
+            // `migrated`/`aborted` outcome the `handle` built above (and its
+            // `nativeDb`) is CLOSED. We therefore re-open this scope fresh
+            // (cache-miss, NOT armed — no `exodusCwd`) and return the new live
+            // handle. That re-open flows through the cold-open lease again on a FRESH handle
+            // (cheap claim/release — the DB is now migrated), with no contention against the
+            // already-released outer lease.
+            //
+            // Armed ONLY when `exodusCwd` was threaded through the canonical
+            // `openDualScopeDb` AND `dbPath` is the canonical path for that scope+cwd —
+            // never for explicit-path opens (test fixtures / legacy-path domains).
+            let finalHandle = handle;
+            if (exodusCwd !== undefined && normalizedPath === resolveDualScopeDbPath(scope, exodusCwd)) {
+                // ── T12001 (Epic T11992) — db-heavy admission for the exodus auto-migrate ──
+                // The on-open exodus (reconcile + parity verify + migrate) is a heavy DB op;
+                // letting it co-schedule with builds/tests/agents is a historical OOM vector.
+                // Admit it through the governor's `db-heavy` class (machine-wide serialized;
+                // deferred under memory backoff). On a denial we SKIP the migration THIS open
+                // (kill-switch precedent CLEO_DISABLE_EXODUS_ON_OPEN) — NEVER block or defer
+                // the interactive command (interactive-cli is never gated) — and it re-runs
+                // idempotently on a calmer open. Fail-open: ANY governor error proceeds
+                // un-gated, byte-identical to pre-T12001 behaviour.
+                let releaseDbHeavy = null;
+                let dbHeavyDeferred = false;
+                try {
+                    const { governor } = await import('../resources/governor.js');
+                    const admit = await governor.tryAcquire('db-heavy');
+                    if (admit.deferred) {
+                        dbHeavyDeferred = true;
+                    }
+                    else {
+                        releaseDbHeavy = admit.release;
+                    }
+                }
+                catch {
+                    // Governor unavailable — fail open (proceed un-gated).
+                }
+                if (dbHeavyDeferred) {
+                    log.debug({ scope, dbPath: normalizedPath }, 'exodus-on-open skipped this open — db-heavy deferred under memory pressure ' +
+                        '(re-runs idempotently on a calmer open)');
+                }
+                else {
+                    try {
+                        const { maybeRunExodusOnOpen } = await import('./exodus/on-open.js');
+                        const result = await maybeRunExodusOnOpen(scope, normalizedPath, nativeDb, exodusCwd);
+                        if (result.outcome === 'migrated' || result.outcome === 'aborted') {
+                            // The migrate engine closed our handle — re-open fresh (un-armed) so the
+                            // caller receives a valid, live handle bound to the now-(de)populated DB.
+                            const reopened = scope === 'project'
+                                ? await openDualScopeDbAtPath('project', normalizedPath)
+                                : await openDualScopeDbAtPath('global', normalizedPath);
+                            if (result.outcome === 'aborted') {
+                                // T11828 (DHQ-059): the data-continuity gate aborted — the consolidated
+                                // DB is empty + consistent, legacy kept as source. Surface this to a
+                                // MUTATING caller (read-only callers ignore it) by (a) stamping a
+                                // structured marker on the returned handle and (b) broadcasting a typed
+                                // event. The non-zero error itself is raised on the write path via
+                                // `assertWriteDurable(handle)` — NOT here, so read opens never throw.
+                                const abort = {
+                                    scope,
+                                    dbPath: normalizedPath,
+                                    reason: result.reason,
+                                    at: Date.now(),
+                                };
+                                log.warn({ scope, reason: result.reason }, 'exodus-on-open aborted; consolidated cleo.db left empty, legacy kept as source — ' +
+                                    'mutating callers must check handle.exodusAbort / call assertWriteDurable (T11828)');
+                                const { emitExodusAbort } = await import('./exodus/abort-events.js');
+                                emitExodusAbort(abort);
+                                finalHandle = { ...reopened, exodusAbort: abort };
+                            }
+                            else {
+                                // A subsequent SUCCESSFUL migration resolves any prior abort recorded
+                                // for this scope, so writes are no longer rejected (T11828).
+                                const { clearExodusAborts } = await import('./exodus/abort-events.js');
+                                clearExodusAborts(scope);
+                                finalHandle = reopened;
+                            }
+                        }
+                    }
+                    catch (err) {
+                        // Best-effort safety net: a hook failure must not make the DB
+                        // unopenable. Warn and re-open fresh; `cleo exodus migrate` remains the
+                        // manual path. (The handle may have been closed mid-migrate.)
+                        log.warn({ err, scope }, 'exodus-on-open hook failed (non-fatal); re-opening consolidated handle');
+                        finalHandle =
+                            scope === 'project'
+                                ? await openDualScopeDbAtPath('project', normalizedPath)
+                                : await openDualScopeDbAtPath('global', normalizedPath);
+                    }
+                    finally {
+                        // Release the db-heavy slot on EVERY exit path (early returns above run
+                        // `finally` first). Idempotent; release errors are swallowed.
+                        if (releaseDbHeavy)
+                            await releaseDbHeavy().catch(() => { });
+                    }
+                }
+            }
+            initResolve(finalHandle);
+        }
+        catch (err) {
+            initReject(err);
+        }
+    })();
     return initPromise;
 }
 /**
@@ -628,13 +670,372 @@ export function _resetDualScopeDbCache(scope) {
         // defensively in case the handle was a mid-init placeholder.
         _cache.delete(key);
     }
-    // Only reset the schema caches on a full (unscoped) reset — a scoped reset must
-    // not force the OTHER scope to reload its schema barrel mid-flight.
-    if (scope === undefined) {
-        _projectSchema = null;
-        _globalSchema = null;
+}
+/**
+ * Error thrown when a runtime entry is cancelled during initialization
+ * (e.g. {@link CleoRuntime.closeProject} called while an open is in flight).
+ */
+class EntryCancelledError extends Error {
+    constructor(scope, dbPath) {
+        super(`CleoRuntime entry cancelled during initialization: ${scope}::${dbPath}`);
+        this.name = 'EntryCancelledError';
     }
 }
+/**
+ * Thrown when the post-await liveness reacquisition exhausts its bounded
+ * retries — two consecutive opens returned a dead handle. The caller can
+ * distinguish a transient liveness loss (one retry succeeds) from a
+ * persistent failure (both handles dead).
+ *
+ * @task T12036 (E6-L12)
+ */
+class LivenessExhaustedError extends Error {
+    constructor(scope, dbPath) {
+        super(`CleoRuntime liveness exhausted after bounded reacquisition: ${scope}::${dbPath}`);
+        this.name = 'LivenessExhaustedError';
+    }
+}
+/**
+ * Concrete implementation of the {@link CleoRuntime} store registry.
+ *
+ * Maintains a private `Map<string, RuntimeEntry>` keyed by the scope-qualified
+ * composite `${scope}::${normalizedDbPath}`. Each call to {@link openProject}
+ * or {@link openGlobal} flows through the existing dual-scope chokepoint
+ * ({@link openDualScopeDbAtPath}) so migrations, pragmas, and the singleton
+ * `_cache` are shared — the runtime adds explicit per-entry wrapping, identity
+ * tracking, and scoped disposal on top.
+ *
+ * ## Key invariants
+ *
+ * 1. **Scope-qualified keys** — `'project::/abs/path'` and
+ *    `'global::/abs/path'` are distinct keys even when the path is the same
+ *    string. A `GlobalStore` can never be cast to a `ProjectStore` via a
+ *    key collision.
+ * 2. **Entry identity** — every entry carries a monotonically-increasing `id`.
+ *    After `await openDualScopeDbAtPath`, the init publishes ONLY when the
+ *    current entry's `id` still matches. If another call (close/re-open)
+ *    replaced the entry, the acquired handle is closed and the init rejects.
+ * 3. **Stale-safe close** — each store records its entry `id`. `close()` only
+ *    evicts the registry entry when its `id` still matches; an old stale close
+ *    is a no-op.
+ * 4. **Cache-hit liveness** — before returning a cached store, the runtime
+ *    checks {@link ProjectStore.isOpen} / {@link GlobalStore.isOpen}
+ *    (which delegates to {@link DualScopeDbHandle.isOpen}, a typed getter
+ *    reflecting the underlying `DatabaseSync.isOpen`). A handle closed
+ *    externally (e.g. `_resetDualScopeDbCache`) is evicted and re-opened.
+ * 5. **Path normalization** — all paths are normalized via `path.resolve()`
+ *    before keying, so `/path/./to/db` and `/path/to/db` share one entry.
+ * 6. **Dedicated mode** — passing `{ dedicated: true }` opens a second
+ *    `DatabaseSync` connection (WAL-allowed) that bypasses the shared cache.
+ *    Dedicated stores are NOT registered or tracked; the caller is responsible
+ *    for closing them.
+ *
+ * @task T12036 (E6-L12)
+ */
+class CleoRuntimeImpl {
+    _registry = new Map();
+    _nextId = 0;
+    /**
+     * Injectable opener function. Defaults to {@link openDualScopeDbAtPath}.
+     * Tests override this to return a pre-closed handle for exercising the
+     * post-await liveness branch. Not part of the public {@link CleoRuntime}
+     * interface.
+     */
+    openDualScopeFn = openDualScopeDbAtPath;
+    /** @inheritdoc */
+    get openPaths() {
+        return new Set(this._registry.keys());
+    }
+    /** @inheritdoc */
+    async openProject(dbPath, options) {
+        const normalized = resolve(dbPath);
+        if (options?.dedicated) {
+            const handle = await openDualScopeDbAtPath('project', normalized, options?.exodusCwd, {
+                dedicated: true,
+            });
+            return this.buildStore('project', handle, 0);
+        }
+        return this.openEntry('project', normalized, 0, options?.exodusCwd);
+    }
+    /** @inheritdoc */
+    async openGlobal(options) {
+        const dbPath = resolveDualScopeDbPath('global');
+        const normalized = resolve(dbPath);
+        if (options?.dedicated) {
+            const handle = await openDualScopeDbAtPath('global', normalized, options?.exodusCwd, {
+                dedicated: true,
+            });
+            return this.buildStore('global', handle, 0);
+        }
+        return this.openEntry('global', normalized, 0, options?.exodusCwd);
+    }
+    /** @inheritdoc */
+    async openGlobalAt(dbPath, options) {
+        const normalized = resolve(dbPath);
+        if (options?.dedicated) {
+            const handle = await openDualScopeDbAtPath('global', normalized, options?.exodusCwd, {
+                dedicated: true,
+            });
+            return this.buildStore('global', handle, 0);
+        }
+        return this.openEntry('global', normalized, 0, options?.exodusCwd);
+    }
+    /** @inheritdoc */
+    closeProject(dbPath) {
+        const normalized = resolve(dbPath);
+        this.closeEntry('project', normalized);
+    }
+    /** @inheritdoc */
+    closeAll() {
+        // Snapshot keys: closeEntry mutates the map during iteration.
+        for (const key of [...this._registry.keys()]) {
+            try {
+                this.closeEntryByKey(key);
+            }
+            catch {
+                // Continue closing remaining entries.
+            }
+        }
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    /**
+     * Open (or reuse) a scoped entry. All five key invariants are enforced
+     * on this single code path.
+     *
+     * @param depth - Reacquisition depth guard. Starts at 0; capped at 1.
+     *   When the post-await liveness check finds a dead handle, the bounded
+     *   retry calls this with `depth + 1`. A second dead handle at depth 1
+     *   throws {@link LivenessExhaustedError} instead of recursing further.
+     */
+    async openEntry(scope, dbPath, depth = 0, 
+    /**
+     * Forwarded to the chokepoint as `exodusCwd` so a runtime open arms the
+     * exodus-on-open legacy-fleet auto-migration exactly like
+     * {@link openDualScopeDb} does. NOT part of the registry key — the key is
+     * the canonical path this cwd already resolved to (T12037).
+     */
+    exodusCwd) {
+        const key = cacheKey(scope, dbPath);
+        // ── Cache-hit liveness (invariant 4) ─────────────────────────────────
+        const existing = this._registry.get(key);
+        if (existing) {
+            if (existing.initPromise) {
+                return existing.initPromise;
+            }
+            if (existing.store?.isOpen) {
+                return existing.store;
+            }
+            // Handle was closed externally — evict and re-open.
+            this._registry.delete(key);
+        }
+        // ── Placeholder with identity (invariant 2) ──────────────────────────
+        const entryId = ++this._nextId;
+        let initResolve;
+        let initReject;
+        const initPromise = new Promise((resolve, reject) => {
+            initResolve = resolve;
+            initReject = reject;
+        });
+        this._registry.set(key, { id: entryId, store: null, initPromise });
+        // Evict on failure so a transient error doesn't poison.
+        initPromise.catch(() => {
+            const placeholder = this._registry.get(key);
+            if (placeholder?.initPromise === initPromise) {
+                this._registry.delete(key);
+            }
+        });
+        try {
+            // Dispatch on scope literal so the overloaded opener resolves to the
+            // correct typed return. The union `DualScope` cannot satisfy either
+            // literal overload directly.
+            const dualHandle = scope === 'project'
+                ? await this.openDualScopeFn('project', dbPath, exodusCwd)
+                : await this.openDualScopeFn('global', dbPath, exodusCwd);
+            // ── Publish only if THIS init is still current (invariant 2) ───────
+            const current = this._registry.get(key);
+            if (!current || current.id !== entryId) {
+                // Cancelled during init. Do NOT close dualHandle — a replacement
+                // entry for the same scope/key may be awaiting the same in-flight
+                // chokepoint promise. The handle stays in the shared cache; the
+                // replacement inherits it live.
+                throw new EntryCancelledError(scope, dbPath);
+            }
+            // ── Post-await liveness (invariant 4b) ─────────────────────────
+            // The chokepoint resolved with a live handle, but an external close
+            // (e.g. _resetDualScopeDbCache or a test-injected dead-handle opener)
+            // between the await and this publish can kill it. If the handle is
+            // dead, close it (evict from cache), delete the placeholder, and
+            // perform ONE bounded reacquisition.
+            if (!dualHandle.isOpen) {
+                dualHandle.close();
+                this._registry.delete(key);
+                if (depth >= 1) {
+                    throw new LivenessExhaustedError(scope, dbPath);
+                }
+                const retryStore = await this.openEntry(scope, dbPath, depth + 1, exodusCwd);
+                initResolve(retryStore);
+                return retryStore;
+            }
+            const store = this.buildStore(scope, dualHandle, entryId);
+            current.store = store;
+            current.initPromise = null;
+            initResolve(store);
+            return store;
+        }
+        catch (err) {
+            initReject(err);
+            throw err;
+        }
+    }
+    /**
+     * Build a typed {@link ProjectStore} or {@link GlobalStore} from a
+     * {@link DualScopeDbHandle}. The store's `close()` is stale-safe
+     * (invariant 3): it only evicts the registry entry when the entry's
+     * identity still matches.
+     */
+    buildStore(scope, dualHandle, entryId) {
+        const dbPath = dualHandle.dbPath;
+        const identity = dualHandle.identity;
+        const exodusAbort = dualHandle.exodusAbort;
+        const key = cacheKey(scope, dbPath);
+        if (scope === 'project') {
+            const store = {
+                scope: 'project',
+                dbPath,
+                identity,
+                db: dualHandle.db,
+                get isOpen() {
+                    return dualHandle.isOpen;
+                },
+                exodusAbort,
+                close: () => {
+                    dualHandle.close();
+                    this.cleanupEntry(key, entryId);
+                },
+            };
+            return store;
+        }
+        const store = {
+            scope: 'global',
+            dbPath,
+            identity,
+            db: dualHandle.db,
+            get isOpen() {
+                return dualHandle.isOpen;
+            },
+            exodusAbort,
+            close: () => {
+                dualHandle.close();
+                this.cleanupEntry(key, entryId);
+            },
+        };
+        return store;
+    }
+    /**
+     * Conditionally evict a registry entry. Only deletes when the current
+     * entry's identity still matches `entryId` — an old stale close is a no-op
+     * (invariant 3).
+     */
+    cleanupEntry(key, entryId) {
+        const entry = this._registry.get(key);
+        if (entry && entry.id === entryId) {
+            this._registry.delete(key);
+        }
+    }
+    /**
+     * Close and evict a single scoped entry from the registry by composite
+     * key. Cancels in-flight opens by deleting the placeholder entry — the
+     * in-flight init detects the missing/id-mismatched entry and rejects
+     * after its `await` resolves (invariant 2).
+     */
+    closeEntry(scope, dbPath) {
+        this.closeEntryByKey(cacheKey(scope, dbPath));
+    }
+    /**
+     * Close and evict a single entry by composite registry key.
+     */
+    closeEntryByKey(key) {
+        const entry = this._registry.get(key);
+        if (!entry)
+            return;
+        // Delete FIRST so in-flight inits observe a missing entry
+        // (invariant 2 — cancellation). Even if the store close below throws,
+        // the entry is gone — the caller won't get it back and the dual-scope
+        // chokepoint cache still owns the SQLite close.
+        this._registry.delete(key);
+        if (entry.store) {
+            try {
+                entry.store.close();
+            }
+            catch {
+                // Close is best-effort; the entry is already evicted.
+            }
+        }
+    }
+}
+/**
+ * Override the dual-scope opener function used by the given
+ * {@link CleoRuntime} instance. Tests inject a custom opener to return a
+ * pre-closed handle, exercising the post-await liveness and bounded-
+ * reacquisition code paths.
+ *
+ * The injected function receives the same `(scope, dbPath)` signature as
+ * {@link openDualScopeDbAtPath} and must return a
+ * {@link DualScopeDbHandle}. Only non-dedicated opens (
+ * {@link CleoRuntime.openProject} and {@link CleoRuntime.openGlobal}
+ * without `{ dedicated: true }`) are affected. Dedicated opens always
+ * call {@link openDualScopeDbAtPath} directly — a custom opener can
+ * never turn a dedicated store into a cached/shared store.
+ *
+ * Pass `undefined` to restore the default (`openDualScopeDbAtPath`).
+ *
+ * @param runtime - The runtime instance to configure.
+ * @param fn - The opener to use, or `undefined` to reset.
+ *
+ * @internal Test seam; imported directly from this module, not the barrel.
+ */
+export function setRuntimeOpenFn(runtime, fn) {
+    runtime.openDualScopeFn = fn ?? openDualScopeDbAtPath;
+}
+/**
+ * Create a new {@link CleoRuntime} store registry.
+ *
+ * The returned runtime is the explicit composition root for project and
+ * global database entries. Use {@link CleoRuntime.openProject} to open a
+ * project's `cleo.db` at a canonical path, and {@link CleoRuntime.openGlobal}
+ * for the global scope. Closing a project via {@link CleoRuntime.closeProject}
+ * or the store's own `close()` disposes only that entry.
+ *
+ * ## Cross-runtime behavior
+ *
+ * Two separate runtime instances SHARE the **process-global dual-scope
+ * handle cache** (`_cache`). Closing a store in one runtime closes the
+ * shared `DatabaseSync` — another runtime referencing the same path
+ * will observe a closed connection. The **cache-hit liveness** check in
+ * this runtime reacquires a fresh handle on the next `openProject`/
+ * `openGlobal`. This is by design: the runtime owns **entry lifecycle**,
+ * not the underlying connection. Use a dedicated connection for isolation.
+ *
+ * @returns A fresh {@link CleoRuntime} instance with an empty registry.
+ *
+ * @example
+ * ```ts
+ * import { createCleoRuntime, resolveDualScopeDbPath } from '@cleocode/core/db';
+ *
+ * const runtime = createCleoRuntime();
+ * const projectA = await runtime.openProject(resolveDualScopeDbPath('project', '/path/to/projA'));
+ * const projectB = await runtime.openProject(resolveDualScopeDbPath('project', '/path/to/projB'));
+ * // projectA and projectB are distinct, independent handles.
+ * projectA.close(); // Only closes projectA; projectB and any global handle are intact.
+ * ```
+ *
+ * @task T12036 (E6-L12)
+ * @epic T11249 (E6)
+ * @saga T11242
+ */
+export function createCleoRuntime() {
+    return new CleoRuntimeImpl();
+}
 /**
  * Attempt to insert `row` into `table`. If a row with the same value for
  * `keyColumn` already exists (UNIQUE conflict), the insert is silently skipped.
@@ -656,6 +1057,11 @@ export function _resetDualScopeDbCache(scope) {
  * the consolidated-schema MUTATION primitives, so the guard is write-only and
  * never affects read paths.
  *
+ * Derives the writer-lease identity from the DB handle itself via
+ * {@link resolveDbIdentity} — the identity was registered at
+ * {@link DualScopeDbHandle} construction, so a caller cannot pair file-A
+ * identity with file-B DB (T12042).
+ *
  * @example
  * ```ts
  * import { tasksTasksTable } from '@cleocode/core/store/schema/cleo-project';
@@ -664,6 +1070,7 @@ export function _resetDualScopeDbCache(scope) {
  *
  * @task T11513 (E4-T2)
  * @task T11828 (write-side exodus-abort guard)
+ * @task T12042 (E6-L12b — exact DB-bound identity)
  * @epic T11247 (E4)
  * @saga T11242
  */
@@ -673,17 +1080,11 @@ db, table, row,
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 _keyColumn) {
     assertNoRecordedExodusAbort();
-    // Seam 1 (T11627 ST-3): gate the chokepoint write through the writer lease so
-    // it serializes with the leased cold-open (Seam 0) and every other chokepoint
-    // write in the process. The scope AND dbPath come from the process-local
-    // active-scope registry recorded at cold-open ({@link activeScope} /
-    // {@link activeScopeDbPath}) — no signature change. Pinning the dbPath keeps the
-    // lease row in the SAME file this write targets when multiple projects are open
-    // (T11627 Finding 1). `off` mode is a pass-through (busy_timeout serializes).
-    return withWriterLease(activeScope(), 'tasks', async () => {
+    const identity = resolveDbIdentity(db);
+    return withWriterLease(identity.scope, 'tasks', async () => {
         const result = await db.insert(table).values(row).onConflictDoNothing().returning();
         return result.length;
-    }, { dbPath: activeScopeDbPath() });
+    }, { dbPath: identity.dbPath });
 }
 /**
  * Upsert `row` into `table`, updating all non-key columns when a row with
@@ -706,6 +1107,9 @@ _keyColumn) {
  * Refuses the write (throws {@link ExodusAbortWriteUnsafeError}) when a prior
  * exodus-on-open aborted in this process (T11828 · DHQ-059) — write-only guard.
  *
+ * Derives the writer-lease identity from the DB handle itself via
+ * {@link resolveDbIdentity} (T12042 — exact DB-bound identity, no fallback).
+ *
  * @example
  * ```ts
  * await upsertIdempotent(db, tasksTasksTable, updatedTask, 'idempotencyKey',
@@ -714,6 +1118,7 @@ _keyColumn) {
  *
  * @task T11513 (E4-T2)
  * @task T11828 (write-side exodus-abort guard)
+ * @task T12042 (E6-L12b — exact DB-bound identity)
  * @epic T11247 (E4)
  * @saga T11242
  */
@@ -725,10 +1130,8 @@ _keyColumn,
 // biome-ignore lint/suspicious/noExplicitAny: column reference type varies by table
 conflictTarget, set) {
     assertNoRecordedExodusAbort();
-    // Seam 1 (T11627 ST-3): gate the chokepoint upsert through the writer lease —
-    // same active-scope-registry path as insertIdempotent (scope + pinned dbPath),
-    // no signature change.
-    return withWriterLease(activeScope(), 'tasks', async () => {
+    const identity = resolveDbIdentity(db);
+    return withWriterLease(identity.scope, 'tasks', async () => {
         const updateSet = set ?? row;
         const result = await db
             .insert(table)
@@ -740,6 +1143,6 @@ conflictTarget, set) {
         })
             .returning();
         return result.length;
-    }, { dbPath: activeScopeDbPath() });
+    }, { dbPath: identity.dbPath });
 }
 //# sourceMappingURL=dual-scope-db.js.map