@cleocode/core 2026.10.3 → 2026.10.5-rc.ci.672

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

@@ -52,22 +52,26 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
-import { ExitCode } from '@cleocode/contracts';
+import { ExitCode } from '@cleocode/contracts/exit-codes.js';
 import { isVaultRemotePath } from '@cleocode/paths';
 import { CleoError } from '../errors.js';
 import { getLogger } from '../logger.js';
 import { getCleoHome, resolveCleoDir } from '../paths.js';
 import { worktreeScope } from '../project-scope.js';
 import { observeOperation } from './background-ops.js';
-import { getRecordedExodusAbort } from './exodus/abort-events.js';
+import { loadNodeSqliteDrizzle } from './drizzle-node-sqlite.js';
+import { EXODUS_DEFERRED_FIX, ExodusAbortWriteUnsafeError, ExodusGuardFailedError, ExodusRunInProgressError, exodusRefusalMessage, exodusRunActiveElsewhere, getRecordedExodusAbort, } from './exodus/abort-events.js';
+import { installExodusWriteGuard, peekExodusWriteGuard } from './exodus/write-guard.js';
 import { ForeignKeysNotRestoredError, migrateBracketed } from './migration-runner.js';
 import { assertStoreNotRelocated } from './relocated-store-guard.js';
 import { resolveConsolidatedJournalSiblings, resolveCorePackageMigrationsFolder, } from './resolve-migrations-folder.js';
-import { healRowIdentitySchema, missingRowIdentitySchema, ROW_IDENTITY } from './row-identity.js';
+import { openUnlessRestoring } from './restore-marker.js';
+import { healRowIdentitySchema, missingRowIdentitySchema, ROW_IDENTITY, registerRowUidFunction, rowIdentityFillPending, } from './row-identity.js';
 import { rowUidFillEnabled } from './row-identity-flag.js';
 import { applyPerfPragmas } from './sqlite-pragmas.js';
-import { captureBracketHooks, syncCaptureOpenPass } from './sync/capture.js';
+import { syncCaptureOpenPass } from './sync/capture.js';
 import { prepareRowIdentityUnderCapture } from './sync/identity-fill.js';
+import { syncMigrationHooks } from './sync/migration-hooks.js';
 import { ensureTriggerSuspendTable, verifyOwnedTriggers } from './sync/trigger-classes.js';
 import { assertWriterVersion } from './sync/writer-version.js';
 import { explainSchemaWriteDenial, installSchemaWriteGuard } from './worktree-build-guard.js';
@@ -95,48 +99,9 @@ export function getDualScopeNativeDb(handle) {
         return db.$client;
     throw new Error(`No native SQLite connection for ${handle.scope}::${handle.dbPath}`);
 }
-/**
- * Thrown by {@link assertWriteDurable} when a MUTATING caller is about to write
- * through a {@link DualScopeDbHandle} whose first-open exodus auto-migration
- * ABORTED (T11828 · DHQ-059).
- *
- * The consolidated `cleo.db` is internally consistent but EMPTY: the user's real
- * data is still in the legacy fleet (kept as the source of truth). Writing here
- * would land in a DB that does not reflect that data, so the write is NOT durable
- * against the source of truth. Read paths never raise this — they intentionally
- * skip {@link assertWriteDurable} and operate on the empty-but-consistent DB.
- *
- * Self-contained (mirrors `BackupRecoverError`) rather than a `CleoError` subclass
- * so the store layer does not need a new numeric `ExitCode` in `@cleocode/contracts`
- * for a condition that is surfaced structurally on the handle.
- *
- * @task T11828
- * @epic T11833
- * @saga T11242
- * @public
- */
-export class ExodusAbortWriteUnsafeError extends Error {
-    /** Stable string error code for envelope `codeName` / log correlation. */
-    codeName = 'E_EXODUS_ABORT_WRITE_UNSAFE';
-    /** The structured abort detail carried by the handle. */
-    detail;
-    /** Remediation hint surfaced to the operator. */
-    fix;
-    /**
-     * @param detail - The {@link ExodusAbortDetail} stamped on the handle.
-     */
-    constructor(detail) {
-        super(`Refusing to write to consolidated ${detail.scope} cleo.db — exodus-on-open ABORTED ` +
-            `(${detail.reason}). The DB is empty; legacy data is the source of truth. ` +
-            `Run \`cleo doctor exodus-health\` then \`cleo exodus migrate\` (or restore via ` +
-            `\`cleo doctor repair --role ${detail.scope === 'project' ? 'tasks' : 'nexus'}\`) before writing.`);
-        this.name = 'ExodusAbortWriteUnsafeError';
-        this.detail = detail;
-        this.fix =
-            'Resolve the aborted migration (`cleo doctor exodus-health` → `cleo exodus migrate`) ' +
-                'so the consolidated cleo.db carries your data before mutating it.';
-    }
-}
+// The refusal error lives with the abort records (exodus/abort-events.ts), a
+// light module the CORE error converters can import (T13167).
+export { ExodusAbortWriteUnsafeError };
 /**
  * Assert that a {@link DualScopeDbHandle} is safe to WRITE through.
  *
@@ -171,23 +136,230 @@ export function assertWriteDurable(handle) {
     }
 }
 /**
- * Throw {@link ExodusAbortWriteUnsafeError} when ANY exodus-on-open abort is
- * recorded for this process (across either scope).
+ * Throw {@link ExodusAbortWriteUnsafeError} when the store behind `db` cannot be
+ * written durably: its exodus-on-open migration is deferred (an active guard on
+ * this connection) or aborted (a recorded abort for this store's path).
  *
  * Used by the consolidated-schema MUTATION primitives ({@link insertIdempotent} /
  * {@link upsertIdempotent}) which do not receive the originating
- * {@link DualScopeDbHandle} — they consult the process-local registry recorded by
- * {@link emitExodusAbort} instead. Read paths never call these primitives, so the
- * guard is write-only.
+ * {@link DualScopeDbHandle}. T13158: matched to the store being written, so a
+ * deferral or abort on one store never refuses another. When the store cannot
+ * be identified, any recorded abort refuses (the T11828 behaviour). Read paths
+ * never call these primitives, so the guard is write-only.
  *
- * @throws {ExodusAbortWriteUnsafeError} When a recorded abort exists.
+ * @param db - The drizzle handle about to be written.
+ * @throws {ExodusAbortWriteUnsafeError} When that store cannot be written durably.
  * @internal
  * @task T11828
+ * @task T13158
  */
-function assertNoRecordedExodusAbort() {
-    const detail = getRecordedExodusAbort();
-    if (detail) {
-        throw new ExodusAbortWriteUnsafeError(detail);
+// biome-ignore lint/suspicious/noExplicitAny: accepts both project and global schema handles
+async function assertNoExodusRefusal(db) {
+    const native = '$client' in db && db.$client instanceof getDatabaseSyncCtor() ? db.$client : null;
+    const path = native?.location() ?? null;
+    if (native === null || path === null) {
+        const detail = getRecordedExodusAbort();
+        // @sync-invariant none:local-only this store's own legacy migration aborted or is pending; never replicated
+        if (detail)
+            throw new ExodusAbortWriteUnsafeError(detail);
+        return;
+    }
+    await assertExodusWriteSafe(native);
+    for (const scope of ['project', 'global']) {
+        const detail = getRecordedExodusAbort(scope);
+        if (detail && detail.kind !== 'deferred' && resolve(detail.dbPath) === resolve(path)) {
+            // @sync-invariant none:local-only this store's own legacy migration aborted; never replicated
+            throw new ExodusAbortWriteUnsafeError(detail);
+        }
+    }
+}
+// ── Deferred exodus-on-open (T13158) ─────────────────────────────────────────
+/**
+ * Refuse a write through `nativeDb` while that store still owes its legacy
+ * migration: exodus-on-open was deferred or aborted while legacy rows wait
+ * (T13158, T13167).
+ *
+ * The production write chokepoints call this first (the task accessor's write
+ * transaction, session creation, {@link insertIdempotent},
+ * {@link upsertIdempotent}), so the caller gets the typed
+ * {@link ExodusAbortWriteUnsafeError} and its remedy rather than a wrapped
+ * SQLite trigger error. The guard is per connection, so one store's refusal
+ * never refuses another. Once the scope's anchor table has rows (the migration
+ * or a reconcile ran, in this process or another) the guard lifts and writes
+ * proceed. The temp triggers remain the backstop for every other write path.
+ *
+ * @param nativeDb - The connection about to be written.
+ * @throws {ExodusAbortWriteUnsafeError} When that store still owes its migration.
+ * @example
+ * ```ts
+ * await assertExodusWriteSafe(nativeDb);
+ * ```
+ * @task T13158
+ * @task T13167
+ */
+export async function assertExodusWriteSafe(nativeDb) {
+    const { activeExodusWriteGuard } = await import('./exodus/write-guard.js');
+    const guard = activeExodusWriteGuard(nativeDb);
+    if (guard !== undefined) {
+        // @sync-invariant none:local-only this store's own legacy migration is pending or aborted; never replicated
+        throw new ExodusAbortWriteUnsafeError(guard.detail);
+    }
+    // T12785: another process is copying legacy rows into this store.
+    const path = nativeDb.location();
+    if (path !== null && exodusRunActiveElsewhere(path)) {
+        // @sync-invariant none:local-only another local process runs this store's legacy migration or reconcile; never replicated
+        throw new ExodusRunInProgressError(path);
+    }
+}
+/** Default bound on how long an open waits for the exodus `db-heavy` slot. */
+const EXODUS_ADMISSION_WAIT_MS = 5_000;
+/**
+ * How long an open waits for `db-heavy` before deferring its exodus migration:
+ * `CLEO_EXODUS_ADMISSION_WAIT_MS` (0–60000), else 5 s. Memory pressure defers at
+ * once regardless; the wait covers a slot another heavy op holds.
+ */
+function exodusAdmissionWaitMs() {
+    const raw = process.env['CLEO_EXODUS_ADMISSION_WAIT_MS'];
+    if (raw === undefined || raw.trim() === '')
+        return EXODUS_ADMISSION_WAIT_MS;
+    const ms = Number(raw);
+    return Number.isInteger(ms) && ms >= 0 && ms <= 60_000 ? ms : EXODUS_ADMISSION_WAIT_MS;
+}
+/** The anchor table whose first row marks a scope's store as populated. */
+function exodusAnchorTable(scope) {
+    return scope === 'project' ? 'tasks_tasks' : 'nexus_project_registry';
+}
+/**
+ * Guard a store that owes its legacy migration (T13158, T13167).
+ *
+ * When this scope's legacy sources hold rows, every INSERT into a table the
+ * migration fills is refused on this connection while the anchor table is
+ * empty (`E_EXODUS_DEFERRED_WRITE_UNSAFE` or `E_EXODUS_ABORT_WRITE_UNSAFE`,
+ * remedy included), and the refusal is recorded. Every handle on the
+ * connection reports it as `exodusAbort`. Called before a pending migration's
+ * handle is published (`deferred`), and on an `aborted` outcome.
+ *
+ * @param nativeDb - The handle's native connection.
+ * @param scope - The scope.
+ * @param dbPath - The consolidated store.
+ * @param cwd - Working directory used to resolve the project root.
+ * @param kind - `deferred` (not run yet) or `aborted`.
+ * @param reason - Why no migration has run, or why it aborted.
+ * @returns `true` when a guard was installed (legacy rows wait).
+ */
+async function guardStrandedStore(nativeDb, scope, dbPath, cwd, kind, reason) {
+    const log = getLogger('dual-scope-db');
+    const { pendingExodusTargets } = await import('./exodus/write-guard.js');
+    let sources;
+    let tables;
+    let sentinels = {};
+    try {
+        ({ sources, tables, sentinels } = await pendingExodusTargets(scope, cwd));
+    }
+    catch (err) {
+        // The legacy files could not be read: assume they hold rows and protect the
+        // anchor table, whose first row would stop the migration for good.
+        log.warn({ err, scope, kind }, 'exodus-on-open: legacy sources could not be assessed');
+        sources = ['legacy stores (unreadable)'];
+        tables = [exodusAnchorTable(scope)];
+    }
+    if (sources.length === 0)
+        return false;
+    const detail = strandedDetail(scope, dbPath, kind, reason, sources);
+    let markerPath = null;
+    try {
+        const { exodusMarkerPath } = await import('./exodus/archive.js');
+        markerPath = exodusMarkerPath(scope, cwd, dbPath);
+    }
+    catch {
+        // No marker location: the guard lifts on the anchor alone.
+    }
+    installExodusWriteGuard(nativeDb, {
+        anchor: exodusAnchorTable(scope),
+        tables: [...new Set([...tables, exodusAnchorTable(scope)])],
+        sentinels,
+        sources,
+        markerPath,
+        detail,
+    }, exodusRefusalMessage(scope, detail.reason, kind));
+    const { emitExodusAbort } = await import('./exodus/abort-events.js');
+    emitExodusAbort(detail);
+    return true;
+}
+/**
+ * Last-resort guard for a store that owes a migration, used when
+ * {@link guardStrandedStore} throws: refuse INSERTs into the scope's anchor
+ * table, whose first row would stop the migration for good. A guard that is
+ * already installed is kept, since it covers more tables.
+ *
+ * @param nativeDb - The handle's native connection.
+ * @param scope - The scope.
+ * @param dbPath - The consolidated store.
+ * @param kind - `deferred` (not run yet) or `aborted`.
+ * @param reason - Why no migration has run, or why it aborted.
+ * @throws {ExodusGuardFailedError} When not even the anchor trigger can be
+ *   installed: the open is refused rather than publishing a store any write
+ *   (raw SQL included) could strand (T13171).
+ */
+function guardAnchorOnly(nativeDb, scope, dbPath, kind, reason) {
+    if (peekExodusWriteGuard(nativeDb) !== undefined)
+        return;
+    const anchor = exodusAnchorTable(scope);
+    const sources = ['stores'];
+    const detail = strandedDetail(scope, dbPath, kind, reason, sources);
+    try {
+        installExodusWriteGuard(nativeDb, { anchor, tables: [anchor], sources, markerPath: null, detail }, exodusRefusalMessage(scope, detail.reason, kind));
+    }
+    catch (err) {
+        getLogger('dual-scope-db').error({ err, scope }, 'exodus-on-open: the store could not be guarded before its migration; refusing the open');
+        // @sync-invariant none:local-only this store's own legacy migration could not be guarded; never replicated
+        throw new ExodusGuardFailedError(scope, err);
+    }
+}
+/** The refusal detail for a store that owes the migration of `sources`. */
+function strandedDetail(scope, dbPath, kind, reason, sources) {
+    return {
+        scope,
+        dbPath,
+        reason: `${reason}; legacy ${sources.join(', ')} still hold rows`,
+        at: Date.now(),
+        kind,
+    };
+}
+/**
+ * Record why a guarded store's migration was deferred this open (T13158):
+ * the refusal detail takes the governor's reason, the deferral is logged with
+ * it, and readers get a `W_EXODUS_DEFERRED` warning.
+ *
+ * @param nativeDb - The guarded connection.
+ * @param scope - The deferred scope.
+ * @param dbPath - The consolidated store.
+ * @param deferral - The governor's reason for deferring.
+ */
+async function announceDeferredExodus(nativeDb, scope, dbPath, deferral) {
+    const log = getLogger('dual-scope-db');
+    const { activeExodusWriteGuard } = await import('./exodus/write-guard.js');
+    const guard = activeExodusWriteGuard(nativeDb);
+    if (guard === undefined)
+        return;
+    const detail = strandedDetail(scope, dbPath, 'deferred', deferral, guard.sources);
+    guard.detail = detail;
+    const { emitExodusAbort } = await import('./exodus/abort-events.js');
+    emitExodusAbort(detail);
+    log.warn({ scope, dbPath, reason: deferral, sources: guard.sources, guardedTables: guard.tables.length }, 'exodus-on-open deferred: the store is empty while legacy rows wait; writes to the ' +
+        'tables the migration fills are refused until it runs (T13158)');
+    try {
+        const { pushWarning } = await import('../output.js');
+        pushWarning({
+            // @sync-invariant none:local-only a read warning about this store's pending legacy migration
+            code: 'W_EXODUS_DEFERRED',
+            message: `The ${scope} store has not been migrated from the legacy stores yet (${deferral}), so ` +
+                `results omit the data in ${guard.sources.join(', ')}. Writes are refused until it ` +
+                `runs. ${EXODUS_DEFERRED_FIX}`,
+        });
+    }
+    catch {
+        // A warning must never fail the open.
     }
 }
 const _cache = new Map();
@@ -249,19 +421,10 @@ export function resolveDualScopeDbPath(scope, cwd, capturedGlobalHome) {
 function migrationsSetName(scope) {
     return scope === 'project' ? 'drizzle-cleo-project' : 'drizzle-cleo-global';
 }
-// ── Lazy drizzle loading ─────────────────────────────────────────────────────
-// The drizzle-orm/node-sqlite driver statically imports `node:sqlite`, so we
-// load it lazily (matching the pattern in sqlite.ts, T11280) to avoid pulling
-// the native binding at module-load time and breaking lazy-init assertions.
+// ── Lazy native loading ──────────────────────────────────────────────────────
+// drizzle's node-sqlite driver loads lazily through ./drizzle-node-sqlite.ts
+// (T11280, T13126). DatabaseSync is lazy too, to avoid an eager node:sqlite pull.
 const _require = createRequire(import.meta.url);
-let _drizzle = null;
-function getDrizzle() {
-    if (_drizzle === null) {
-        const mod = _require('drizzle-orm/node-sqlite');
-        _drizzle = mod.drizzle;
-    }
-    return _drizzle;
-}
 let _DatabaseSyncCtor = null;
 function getDatabaseSyncCtor() {
     if (_DatabaseSyncCtor === null) {
@@ -396,7 +559,7 @@ db, migrationsFolder, log, execution) {
         }
     }
     execution?.assertActive();
-    migrateBracketed(db, nativeDb, migrationsFolder, existenceTable(scope), `dual-scope-db[${scope}]`, resolveConsolidatedJournalSiblings(migrationsSetName(scope)), captureBracketHooks(nativeDb, scope));
+    migrateBracketed(db, nativeDb, migrationsFolder, existenceTable(scope), `dual-scope-db[${scope}]`, resolveConsolidatedJournalSiblings(migrationsSetName(scope)), syncMigrationHooks(nativeDb, scope));
     // NEW-6: the handle leaves the schema pass in its configured FK mode.
     assertHandleForeignKeys(nativeDb);
     execution?.assertActive();
@@ -431,13 +594,27 @@ db, migrationsFolder, log, execution) {
     }
 }
 /**
- * Whether this open has row-identity work: the fill (flag on), or identity
- * schema to heal (T12878). A scope with nothing declared has none.
+ * Whether the schema pass has row-identity work: identity schema to heal
+ * (T12878). A scope with nothing declared has none. The fill is decided after
+ * the schema pass by {@link rowIdentityFillPending} (T12341 C1).
  */
 function identityWorkOnOpen(nativeDb, scope) {
     if (ROW_IDENTITY[scope].length === 0)
         return false;
-    return rowUidFillEnabled() || missingRowIdentitySchema(nativeDb).length > 0;
+    return missingRowIdentitySchema(nativeDb).length > 0;
+}
+/**
+ * The fill's pending work for this open, with the identity SQL functions
+ * registered. The chokepoint writers load only when there is work: a store the
+ * fill already completed opens without loading `sqlite-data-accessor` (T12341
+ * C1; it cost ~170 ms and ~15 MB on every open).
+ */
+async function prepareFillWriters(nativeDb, scope) {
+    registerRowUidFunction(nativeDb, scope);
+    const pending = rowIdentityFillPending(nativeDb, scope);
+    if (pending.length > 0)
+        await import('./sqlite-data-accessor.js');
+    return pending;
 }
 /**
  * Open a DEDICATED, NON-cached consolidated dual-scope `cleo.db` connection
@@ -468,7 +645,8 @@ async function openDedicatedDualScopeDb(scope, dbPath, log, execution) {
     }
     execution?.assertActive();
     const DatabaseSyncCtor = getDatabaseSyncCtor();
-    const nativeDb = new DatabaseSyncCtor(dbPath, { allowExtension: true });
+    // T13258: never open a store file a restore is replacing (before and after the open).
+    const nativeDb = openUnlessRestoring(dbPath, () => new DatabaseSyncCtor(dbPath, { allowExtension: true }));
     // Every operation after construction is wrapped so any exception —
     // pragmas, Drizzle wrapping, migration-folder resolution, lease, or
     // migration — closes the native handle before rethrow.
@@ -478,7 +656,7 @@ async function openDedicatedDualScopeDb(scope, dbPath, log, execution) {
         // T12687: a worktree build may not change a foreign store's schema — deny
         // every DDL on this handle before any schema code runs.
         installSchemaWriteGuard(nativeDb);
-        const drizzle = getDrizzle();
+        const drizzle = loadNodeSqliteDrizzle();
         // 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));
@@ -496,9 +674,9 @@ async function openDedicatedDualScopeDb(scope, dbPath, log, execution) {
             // writers were loaded there when the fill is on.
             execution?.assertActive();
             if (rowUidFillEnabled() && ROW_IDENTITY[scope].length > 0) {
-                await import('./sqlite-data-accessor.js');
+                const pending = await prepareFillWriters(nativeDb, scope);
                 // Uncaptured under sync capture, with its tables marked suspect.
-                prepareRowIdentityUnderCapture(nativeDb, scope, { triggers: false });
+                prepareRowIdentityUnderCapture(nativeDb, scope, { triggers: false, pending });
             }
             execution?.assertActive();
             log.debug({ scope, dbPath }, 'DEDICATED dual-scope cleo.db ready (T11782 FIX D)');
@@ -663,6 +841,9 @@ exodusCwd, options) {
     (async () => {
         let openingNative = null;
         let published = false;
+        // T13158: the exodus assessment, made BEFORE the handle is published (a
+        // holder object: the lease callback assigns it).
+        const exodusState = { preparation: null };
         try {
             execution?.assertActive();
             log.debug({ scope, dbPath: normalizedPath }, 'opening dual-scope cleo.db');
@@ -682,7 +863,8 @@ exodusCwd, options) {
             // single-keyed regardless of which domain opens the handle first.
             execution?.assertActive();
             const DatabaseSyncCtor = getDatabaseSyncCtor();
-            const nativeDb = new DatabaseSyncCtor(normalizedPath, { allowExtension: true });
+            // T13258: never open a store file a restore is replacing (before and after the open).
+            const nativeDb = openUnlessRestoring(normalizedPath, () => new DatabaseSyncCtor(normalizedPath, { allowExtension: true }));
             openingNative = nativeDb;
             // Apply canonical pragma set (specs/sqlite-pragmas.json SSoT), bounding
             // per-connection memory for one-shot/CLI opens (full SSoT for daemon) — T11829.
@@ -691,7 +873,7 @@ exodusCwd, options) {
             // every DDL on this handle before any schema code runs.
             installSchemaWriteGuard(nativeDb);
             // Create the Drizzle ORM wrapper.
-            const drizzle = getDrizzle();
+            const drizzle = loadNodeSqliteDrizzle();
             // 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.
@@ -732,9 +914,9 @@ exodusCwd, options) {
                 // once, and arm this connection's uid triggers. Never throws.
                 execution?.assertActive();
                 if (rowUidFillEnabled() && ROW_IDENTITY[scope].length > 0) {
-                    await import('./sqlite-data-accessor.js');
+                    const pending = await prepareFillWriters(nativeDb, scope);
                     // A derived rewrite: uncaptured, its tables marked suspect (S2).
-                    prepareRowIdentityUnderCapture(nativeDb, scope);
+                    prepareRowIdentityUnderCapture(nativeDb, scope, { pending });
                 }
                 execution?.assertActive();
                 log.debug({ scope, dbPath: normalizedPath }, 'dual-scope cleo.db ready');
@@ -748,6 +930,12 @@ exodusCwd, options) {
                     get isOpen() {
                         return nativeDb.isOpen;
                     },
+                    // T13158 / T13167: the marker is the connection's write guard, so
+                    // every in-process holder sees a deferral or abort set (or lifted)
+                    // after publication.
+                    get exodusAbort() {
+                        return peekExodusWriteGuard(nativeDb)?.detail;
+                    },
                     close() {
                         // Identity-guarded deletion: only evict from the singleton cache
                         // when the current entry still references THIS exact handle. A stale
@@ -765,6 +953,53 @@ exodusCwd, options) {
                         }
                     },
                 };
+                // T13158: never publish an unguarded handle for a store that still
+                // owes a migration. Publication hands this connection to every
+                // concurrent in-process open, and an INSERT through it before the
+                // migration (or its guard) would make the store look populated and
+                // strand the legacy rows. So assess first, and when a migration is
+                // pending, guard the connection before anyone else can see it.
+                // Populated stores cost one COUNT(*) here.
+                if (exodusCwd !== undefined &&
+                    normalizedPath === resolveDualScopeDbPath(scope, exodusCwd)) {
+                    try {
+                        execution?.assertActive();
+                        const { prepareExodusOnOpen } = await import('./exodus/on-open.js');
+                        execution?.assertActive();
+                        exodusState.preparation = await prepareExodusOnOpen(scope, normalizedPath, nativeDb, exodusCwd);
+                    }
+                    catch (err) {
+                        execution?.assertActive();
+                        exodusState.preparation = null;
+                        log.warn({ err, scope }, 'exodus-on-open assessment unavailable (non-fatal)');
+                    }
+                    // An abort decided at assessment (unreadable marker, plan mismatch,
+                    // assessment failure) owes the same protection before publication
+                    // as a pending migration (#1839 review HIGH): the post-lease abort
+                    // branch would guard only after concurrent opens could write.
+                    const preparation = exodusState.preparation;
+                    const stranded = preparation?.kind === 'pending'
+                        ? { kind: 'deferred', reason: 'its migration has not run yet' }
+                        : preparation?.kind === 'decided' && preparation.result.outcome === 'aborted'
+                            ? { kind: 'aborted', reason: preparation.result.reason }
+                            : null;
+                    if (stranded !== null) {
+                        try {
+                            execution?.assertActive();
+                            await guardStrandedStore(nativeDb, scope, normalizedPath, exodusCwd, stranded.kind, stranded.reason);
+                        }
+                        catch (err) {
+                            execution?.assertActive();
+                            // A failed guard must cost neither the migration nor the
+                            // protection (#1836 review LOW-a): the preparation stays
+                            // pending, so the migration still runs after the lease, and the
+                            // anchor table is guarded at the least. If even that fails, the
+                            // open is refused (E_EXODUS_GUARD_FAILED, T13171).
+                            log.warn({ err, scope }, 'exodus-on-open: the store could not be fully guarded before its migration');
+                            guardAnchorOnly(nativeDb, scope, normalizedPath, stranded.kind, stranded.reason);
+                        }
+                    }
+                }
                 execution?.assertActive();
                 // Update the cache entry to mark init complete.
                 const entry = _cache.get(key);
@@ -803,46 +1038,73 @@ exodusCwd, options) {
             execution?.assertActive();
             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.
+                // ── Exodus-on-open admission (T12001 · T13158) ──────────────────────────
+                // Decide first, without a lock or the governor, whether this open needs
+                // a migration at all: a populated store costs one COUNT(*), and only a
+                // PENDING migration (empty store, this scope's legacy sources present)
+                // asks for admission. The migration (reconcile + parity verify + copy)
+                // is a heavy DB op, so it runs in the governor's machine-wide `db-heavy`
+                // class, waiting a bounded time for the slot (T13158): `db-heavy` has one
+                // slot machine-wide, so a sentient tick, a `cleo run --class db` job,
+                // another project's exodus or a second `cleo` racing this first open
+                // would otherwise defer it. Memory pressure still defers it at once
+                // (CPU saturation never does: db-heavy is budgeted on memory alone, T13170).
+                //
+                // A migration still deferred after the wait does not run this open, and
+                // the command gets the EMPTY store. While legacy rows wait, a write there
+                // would strand them (a populated store never migrates), so the store
+                // refuses INSERTs into every table the migration fills and readers are
+                // warned (`guardStrandedStore`). The next open admits it again.
+                // Fail-open: a governor error proceeds un-gated, as before T12001.
                 let releaseDbHeavy = null;
-                let dbHeavyDeferred = false;
-                try {
-                    execution?.assertActive();
-                    const { governor } = await import('../resources/governor.js');
-                    execution?.assertActive();
-                    const admit = await governor.tryAcquire('db-heavy');
-                    if (admit.deferred) {
-                        dbHeavyDeferred = true;
+                let deferral = null;
+                const preparation = exodusState.preparation;
+                if (preparation?.kind === 'pending') {
+                    // The connection was guarded before publication (above). The guard
+                    // stays up through the admission wait AND the migration: the copy runs
+                    // on dedicated connections that never see its temp triggers, and the
+                    // triggers stop refusing on their own once the copy commits the anchor.
+                    try {
+                        execution?.assertActive();
+                        const { governor } = await import('../resources/governor.js');
+                        execution?.assertActive();
+                        const admit = await governor.acquire('db-heavy', {
+                            blocking: true,
+                            timeoutMs: exodusAdmissionWaitMs(),
+                        });
+                        if (admit.deferred) {
+                            deferral = admit.reason;
+                        }
+                        else {
+                            releaseDbHeavy = admit.release;
+                        }
                     }
-                    else {
-                        releaseDbHeavy = admit.release;
+                    catch {
+                        execution?.assertActive();
+                        // Governor unavailable — fail open (proceed un-gated).
+                    }
+                    if (deferral !== null) {
+                        await announceDeferredExodus(nativeDb, scope, normalizedPath, deferral);
                     }
                 }
-                catch {
-                    execution?.assertActive();
-                    // Governor unavailable — fail open (proceed un-gated).
-                }
-                if (dbHeavyDeferred) {
-                    execution?.assertActive();
-                    log.debug({ scope, dbPath: normalizedPath }, 'exodus-on-open skipped this open — db-heavy deferred under memory pressure ' +
-                        '(re-runs idempotently on a calmer open)');
+                if (preparation === null || deferral !== null) {
+                    // Assessment unavailable, or the migration deferred: the published
+                    // handle (guarded when legacy rows wait) is returned as opened.
                 }
                 else {
+                    const ready = preparation;
                     try {
                         execution?.assertActive();
-                        const { maybeRunExodusOnOpen } = await import('./exodus/on-open.js');
-                        execution?.assertActive();
-                        const result = await maybeRunExodusOnOpen(scope, normalizedPath, nativeDb, exodusCwd);
+                        const result = ready.kind === 'decided' ? ready.result : await ready.run();
                         execution?.assertActive();
                         if (result.outcome === 'migrated' || result.outcome === 'aborted') {
+                            if (result.outcome === 'migrated') {
+                                // The store now holds the legacy data: the pre-publication guard
+                                // (if this connection is still open and cached) comes down (T13158).
+                                // On `aborted` it stays: the store is still empty while legacy rows wait.
+                                const { liftExodusWriteGuard } = await import('./exodus/write-guard.js');
+                                liftExodusWriteGuard(nativeDb);
+                            }
                             // 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'
@@ -855,17 +1117,43 @@ exodusCwd, options) {
                                 // 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 };
+                                    'writes to the tables the migration fills are refused (T11828, T13167)');
+                                // T13167: while legacy rows wait, guard the store the caller gets
+                                // exactly as a deferral is guarded: every INSERT into a table the
+                                // migration fills refuses, and the typed write checks and the
+                                // handle's `exodusAbort` marker report the abort.
+                                const guarded = await guardStrandedStore(getDualScopeNativeDb(reopened), scope, normalizedPath, exodusCwd, 'aborted', result.reason);
+                                if (guarded) {
+                                    finalHandle = reopened;
+                                    try {
+                                        const { pushWarning } = await import('../output.js');
+                                        pushWarning({
+                                            // @sync-invariant none:local-only a read warning about this store's aborted legacy migration
+                                            code: 'W_EXODUS_ABORTED',
+                                            message: `The ${scope} store's migration from the legacy stores aborted ` +
+                                                `(${result.reason}), so results omit the legacy data. Writes are refused ` +
+                                                'until it is resolved: run `cleo doctor exodus-health`, then ' +
+                                                '`cleo exodus migrate`.',
+                                        });
+                                    }
+                                    catch {
+                                        // A warning must never fail the open.
+                                    }
+                                }
+                                else {
+                                    // No legacy rows at risk: record and mark the abort as before.
+                                    const abort = {
+                                        scope,
+                                        dbPath: normalizedPath,
+                                        reason: result.reason,
+                                        at: Date.now(),
+                                        kind: 'aborted',
+                                    };
+                                    const { emitExodusAbort } = await import('./exodus/abort-events.js');
+                                    emitExodusAbort(abort);
+                                    finalHandle = { ...reopened, exodusAbort: abort };
+                                }
                             }
                             else {
                                 // A subsequent SUCCESSFUL migration resolves any prior abort recorded
@@ -875,6 +1163,12 @@ exodusCwd, options) {
                                 finalHandle = reopened;
                             }
                         }
+                        else if (ready.kind === 'pending') {
+                            // Skipped after all (a concurrent process migrated it first): the
+                            // store owes nothing more, so the guard comes down (T13158).
+                            const { liftExodusWriteGuard } = await import('./exodus/write-guard.js');
+                            liftExodusWriteGuard(nativeDb);
+                        }
                     }
                     catch (err) {
                         execution?.assertActive();
@@ -1385,7 +1679,7 @@ export async function insertIdempotent(
 db, table, row, 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 _keyColumn) {
-    assertNoRecordedExodusAbort();
+    await assertNoExodusRefusal(db);
     const identity = resolveDbIdentity(db);
     return withWriterLease(identity.scope, 'tasks', async () => {
         const result = await db.insert(table).values(row).onConflictDoNothing().returning();
@@ -1435,7 +1729,7 @@ db, table, row,
 _keyColumn, 
 // biome-ignore lint/suspicious/noExplicitAny: column reference type varies by table
 conflictTarget, set) {
-    assertNoRecordedExodusAbort();
+    await assertNoExodusRefusal(db);
     const identity = resolveDbIdentity(db);
     return withWriterLease(identity.scope, 'tasks', async () => {
         const updateSet = set ?? row;