@cleocode/core 2026.9.20 → 2026.9.22

package/dist/store/sqlite-backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-backup.d.ts","sourceRoot":"","sources":["../../src/store/sqlite-backup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqlite-backup.d.ts","sourceRoot":"","sources":["../../src/store/sqlite-backup.ts"],"names":[],"mappings":"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"}

package/dist/store/sqlite-backup.js

@@ -40,8 +40,8 @@
  *                (Saga T10281 / Epic T10284 / E3)
  * @epic T4867
  */
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, } from 'node:fs';
-import { join } from 'node:path';
+import { chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
 import { DB_INVENTORY } from '@cleocode/contracts';
 import { getCleoDir, getCleoHome, resolveOrCwd } from '../paths.js';
 import { getTelemetryDb, getTelemetryNativeDb } from '../telemetry/sqlite.js';
@@ -51,16 +51,14 @@ import { getGlobalSaltPath } from './global-salt.js';
 import { getBrainDb, getBrainNativeDb } from './memory-sqlite.js';
 import { getNexusDb, getNexusNativeDb } from './nexus-sqlite.js';
 import { getSkillsNativeDb, openSkillsDb } from './skills-db.js';
+import { readSnapshotGeneration, runGatedSnapshot, selectSnapshotsToKeep, } from './snapshot-gate.js';
 import { getDb, getNativeDb } from './sqlite.js';
-/** Maximum number of snapshots retained per database (oldest rotated out). */
-const MAX_SNAPSHOTS = 10;
-/** Debounce window (ms) during which duplicate snapshot requests are suppressed. */
-const DEBOUNCE_MS = 30_000; // 30 seconds
 /**
- * Per-database snapshot book-keeping: last snapshot timestamp (epoch ms)
- * keyed by the canonical snapshot prefix (e.g. `"tasks"` / `"brain"`).
+ * Maximum number of snapshots retained per global-tier database and for the
+ * global-salt backups (oldest rotated out). Project-tier snapshots use the
+ * time-spread policy in `snapshot-gate.ts` instead (T12508).
  */
-const _lastBackupEpoch = {};
+const MAX_SNAPSHOTS = 10;
 /**
  * Resolve the path on disk for a given `DB_INVENTORY` row.
  *
@@ -126,8 +124,9 @@ async function openTasksDbForSnapshot(cwd) {
 async function openConduitDbForSnapshot(cwd) {
     // ensureConduitDb requires an absolute project root. E6-L3 (T11523): it is now
     // async (routes through the dual-scope cleo.db chokepoint).
-    await ensureConduitDb(resolveOrCwd(cwd));
-    return getConduitNativeDb();
+    const projectRoot = resolveOrCwd(cwd);
+    await ensureConduitDb(projectRoot);
+    return getConduitNativeDb(projectRoot);
 }
 // ---------------------------------------------------------------------------
 // Global-tier openers (chokepoint-opener strategy)
@@ -227,24 +226,28 @@ function buildRawFileVacuumOpener(entry) {
         const path = resolveInventoryPath(entry, cwd);
         if (!path)
             return null;
-        if (!existsSync(path))
-            return null;
+        // T12508: `existsSync` answers false for EACCES too, which would class an
+        // unreadable database as absent. Only ENOENT means absent; any other stat
+        // error is a failure and propagates.
         try {
-            // Dynamic import preserves the T1331 lazy-init contract: importing
-            // sqlite.ts (which statically imports sqlite-backup.ts for
-            // `listSqliteBackups`) MUST NOT pull node:sqlite into module-load
-            // time. Only the raw-file-vacuum-readonly path needs the
-            // constructor, and it is exercised at snapshot-time, not load-time.
-            const { DatabaseSync } = await import('node:sqlite');
-            return new DatabaseSync(path, { readOnly: true });
+            statSync(path);
         }
-        catch {
-            // The file might be locked by another writer, corrupt, or otherwise
-            // unopenable. Skip silently — snapshot failure must never block
-            // normal operation (and the malformed-DB case is exactly why the
-            // saga exists).
-            return null;
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'ENOENT')
+                return null;
+            throw err;
         }
+        // Dynamic import preserves the T1331 lazy-init contract: importing
+        // sqlite.ts (which statically imports sqlite-backup.ts for
+        // `listSqliteBackups`) MUST NOT pull node:sqlite into module-load
+        // time. Only the raw-file-vacuum-readonly path needs the
+        // constructor, and it is exercised at snapshot-time, not load-time.
+        //
+        // T12508: an existing file that cannot be opened (locked, corrupt) THROWS
+        // here. That is a failure, not an absent database; the gate reports it
+        // and every caller stays non-fatal.
+        const { DatabaseSync } = await import('node:sqlite');
+        return new DatabaseSync(path, { readOnly: true });
     };
 }
 /**
@@ -430,31 +433,282 @@ function snapshotPattern(prefix) {
     return new RegExp(`^${safe}-\\d{8}-\\d{6}\\.db$`);
 }
 /**
- * Rotate snapshots for a single prefix: delete the oldest files until fewer
- * than {@link MAX_SNAPSHOTS} remain. Non-fatal on any filesystem error.
+ * Apply time-spread retention to a single prefix: delete every snapshot not
+ * selected by {@link selectSnapshotsToKeep} (latest, quarter-hourly, hourly
+ * and daily slots). Runs AFTER the new snapshot is written, so a failed
+ * `VACUUM INTO` never costs an existing recovery point, and the file just
+ * written is pinned. Non-fatal on any filesystem error.
+ *
+ * @param backupDir - Snapshot directory.
+ * @param prefix - Snapshot prefix to prune.
+ * @param justWritten - Basename of the snapshot just written; never deleted.
+ * @task T12508 — replaces the newest-10 rotation that a burst could flush
  */
-function rotateSnapshots(backupDir, prefix) {
+function rotateSnapshots(backupDir, prefix, justWritten) {
     try {
         const pattern = snapshotPattern(prefix);
-        const files = readdirSync(backupDir)
-            .filter((f) => pattern.test(f))
-            .map((f) => ({
-            name: f,
-            path: join(backupDir, f),
-            mtimeMs: statSync(join(backupDir, f)).mtimeMs,
-        }))
-            .sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
-        while (files.length >= MAX_SNAPSHOTS) {
-            const oldest = files.shift();
-            if (!oldest)
-                break;
-            unlinkSync(oldest.path);
+        const names = readdirSync(backupDir).filter((f) => pattern.test(f));
+        const keep = selectSnapshotsToKeep(names, {
+            pinned: justWritten,
+            nowStamp: formatTimestamp(new Date()),
+        });
+        for (const name of names) {
+            if (keep.has(name))
+                continue;
+            try {
+                unlinkSync(join(backupDir, name));
+            }
+            catch {
+                // non-fatal — try the rest
+            }
         }
     }
     catch {
         // non-fatal
     }
 }
+/**
+ * Resolve the project `cleo.db` handle that stores the snapshot gate state
+ * (see `snapshot-gate.ts`). Returns `null` when it cannot be opened, in which
+ * case the gate admits no snapshot.
+ *
+ * @task T12508
+ */
+async function resolveGateStateDb(cwd) {
+    try {
+        const bound = getNativeDb(cwd);
+        if (bound)
+            return bound;
+        await getDb(cwd);
+        return getNativeDb(cwd);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the project's current snapshot generation — what a `required` request
+ * should record as `seenGeneration` at the moment it is made (after the
+ * caller's last write), when the snapshot itself runs later or elsewhere.
+ *
+ * @param cwd - Project directory.
+ * @returns The generation, or `null` when the gate state cannot be read.
+ * @task T12508
+ */
+export async function readProjectSnapshotGeneration(cwd) {
+    return readSnapshotGeneration(await resolveGateStateDb(cwd));
+}
+/**
+ * Snapshot the given project-tier targets through the project-wide gate:
+ * one snapshot in flight per project across processes, and a per-prefix
+ * debounce persisted in `cleo.db`. Non-fatal.
+ *
+ * @returns The gate outcome, or `null` when the backup directory cannot be
+ *          resolved or no target is snapshottable.
+ * @task T12508
+ */
+async function snapshotProjectTargetsGated(targets, opts) {
+    const cwd = opts.cwd;
+    let backupDir;
+    try {
+        const cleoDir = getCleoDir(cwd);
+        backupDir = join(cleoDir, 'backups', 'sqlite');
+        mkdirSync(backupDir, { recursive: true });
+    }
+    catch {
+        return null; // cannot resolve backup dir — abort silently
+    }
+    const byPrefix = new Map(targets.filter((t) => t.strategy !== 'skip-derived').map((t) => [t.prefix, t]));
+    if (byPrefix.size === 0)
+        return null;
+    // One VACUUM per physical database file per run (T12508): tasks, brain and
+    // conduit share the project cleo.db handle. Maps source realpath → the
+    // snapshot file written for it in this run.
+    const writtenBySource = new Map();
+    return runGatedSnapshot({
+        backupDir,
+        stateDb: await resolveGateStateDb(cwd),
+        prefixes: [...byPrefix.keys()],
+        mode: opts.mode ?? 'routine',
+        ...(opts.seenGeneration !== undefined && { seenGeneration: opts.seenGeneration }),
+        ...(opts.alwaysSnapshot !== undefined && { alwaysSnapshot: opts.alwaysSnapshot }),
+        ...(opts.lockWaitRetries !== undefined && { lockWaitRetries: opts.lockWaitRetries }),
+        ...(opts.onLockAcquired !== undefined && { onLockAcquired: opts.onLockAcquired }),
+    }, async (prefix) => {
+        const target = byPrefix.get(prefix);
+        return target ? snapshotOne(target, backupDir, writtenBySource, cwd) : 'absent';
+    });
+}
+/**
+ * Real path of the database file behind a native handle, or `null` when it is
+ * unknown (an in-memory database, or a handle without `location()`).
+ *
+ * @task T12508
+ */
+function sourceFileOf(db) {
+    if (!hasLocation(db))
+        return null;
+    const location = db.location();
+    if (!location)
+        return null;
+    try {
+        return realpathSync(location);
+    }
+    catch {
+        return location;
+    }
+}
+/** Whether a handle exposes `DatabaseSync.location()` (Node 24+). */
+function hasLocation(db) {
+    return 'location' in db && typeof db.location === 'function';
+}
+/**
+ * Refuse to snapshot a project-tier handle whose file lies outside this
+ * project's `.cleo/` directory. A handle resolved for the wrong project (the
+ * ambient one in a multi-project process) would otherwise put project B's
+ * database into project A's backups.
+ *
+ * @task T12508
+ */
+function assertOwnedByProject(source, prefix, cwd) {
+    let cleoDir = getCleoDir(cwd);
+    try {
+        cleoDir = realpathSync(cleoDir);
+    }
+    catch {
+        // Compare against the unresolved path.
+    }
+    if (!source.startsWith(cleoDir + sep)) {
+        throw new Error(`refusing to snapshot ${prefix}: its database ${source} is not inside ${cleoDir}`);
+    }
+}
+/**
+ * `link()` error codes that mean "this filesystem cannot hard-link these
+ * files" rather than a real failure: permission-less link (EPERM), no link
+ * support (ENOTSUP, e.g. exFAT), different devices (EXDEV), link-count cap
+ * (EMLINK). The caller copies instead.
+ */
+const LINK_FALLBACK_CODES = new Set(['EPERM', 'ENOTSUP', 'EXDEV', 'EMLINK']);
+/**
+ * Hard-link `existing` to `dest`. Returns `false` when the filesystem cannot
+ * hard-link (see {@link LINK_FALLBACK_CODES}); any other error throws.
+ *
+ * @task T12508
+ */
+function tryHardLink(existing, dest) {
+    try {
+        linkSync(existing, dest);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && typeof err.code === 'string') {
+            if (LINK_FALLBACK_CODES.has(err.code))
+                return false;
+        }
+        throw err;
+    }
+}
+/**
+ * An in-progress snapshot file `<name>.tmp-<pid>`, or a SQLite sidecar
+ * (`-journal`, `-wal`, `-shm`) that `VACUUM INTO` may leave beside it.
+ */
+const TEMP_SNAPSHOT_RE = /\.db\.tmp-(\d+)(?:-journal|-wal|-shm)?$/;
+/** Age after which any temp snapshot is a leftover, even if its pid was reused. */
+const TEMP_SNAPSHOT_MAX_AGE_MS = 60 * 60_000;
+/**
+ * Temp path a snapshot is written to before it is committed. It does not end
+ * in `.db`, so every snapshot reader (listing, retention, restore, doctor)
+ * ignores it.
+ */
+function tempSnapshotPath(dest) {
+    return `${dest}.tmp-${process.pid}`;
+}
+/**
+ * Make a finished temp snapshot durable and give it its real name: fsync the
+ * file, rename it (atomic within a directory), then fsync the directory
+ * (best-effort) so the rename itself survives a crash.
+ *
+ * @task T12508
+ */
+function commitSnapshotFile(tmp, dest) {
+    const fd = openSync(tmp, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, dest);
+    try {
+        const dirFd = openSync(dirname(dest), 'r');
+        try {
+            fsyncSync(dirFd);
+        }
+        finally {
+            closeSync(dirFd);
+        }
+    }
+    catch {
+        // Not every platform can fsync a directory; the rename is still atomic.
+    }
+}
+/** Whether a process with this pid exists (EPERM means it exists but is not ours). */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err instanceof Error && 'code' in err && err.code === 'EPERM';
+    }
+}
+/**
+ * Remove temp snapshots left by a process killed mid-write: those whose pid
+ * is dead, or that are older than {@link TEMP_SNAPSHOT_MAX_AGE_MS}. Never
+ * throws.
+ *
+ * @task T12508
+ */
+function removeDeadTempSnapshots(backupDir) {
+    try {
+        for (const name of readdirSync(backupDir)) {
+            const m = TEMP_SNAPSHOT_RE.exec(name);
+            if (!m)
+                continue;
+            const pid = Number(m[1]);
+            const path = join(backupDir, name);
+            const stale = pid !== process.pid &&
+                (!isPidAlive(pid) || Date.now() - statSync(path).mtimeMs > TEMP_SNAPSHOT_MAX_AGE_MS);
+            if (stale)
+                rmSync(path, { force: true });
+        }
+    }
+    catch {
+        // Cleanup is best-effort.
+    }
+}
+/** Attempts at finding a free snapshot filename before giving up. */
+const SNAPSHOT_NAME_ATTEMPTS = 3;
+/**
+ * Choose a snapshot filename `<prefix>-YYYYMMDD-HHmmss.db` that does not yet
+ * exist. `VACUUM INTO` refuses an existing destination, and two snapshots of
+ * one prefix can fall in the same second (a routine checkpoint followed by a
+ * pre-destructive one). On a collision this waits for the next second rather
+ * than adding a suffix, so every reader of the documented filename format
+ * (listing, restore, verify, doctor) keeps working. Called under the gate
+ * lock, so no other gated writer can take the name in between.
+ *
+ * @task T12508
+ */
+async function freeSnapshotName(backupDir, prefix) {
+    for (let attempt = 0; attempt < SNAPSHOT_NAME_ATTEMPTS; attempt++) {
+        const name = `${prefix}-${formatTimestamp(new Date())}.db`;
+        if (!existsSync(join(backupDir, name)))
+            return name;
+        await new Promise((r) => setTimeout(r, 1000 - (Date.now() % 1000) + 5));
+    }
+    throw new Error(`no free snapshot filename for ${prefix} in ${backupDir}`);
+}
 /**
  * Create a VACUUM INTO snapshot of a single SQLite database.
  *
@@ -478,21 +732,31 @@ function rotateSnapshots(backupDir, prefix) {
  * {@link vacuumIntoBackupAll}; failures here must never block normal
  * operation.
  *
+ * The filename is stamped HERE, under the gate lock, not when the request
+ * was made — see {@link freeSnapshotName}.
+ *
  * @param target — snapshot target descriptor (role + prefix + native DB getter)
  * @param backupDir — absolute path to the snapshot directory
- * @param now — reference timestamp for the filename
  * @param cwd — optional working directory propagated to `target.openDb`
+ * @param writtenBySource — snapshot files already written in this run, keyed
+ *        by source realpath; a second target on the same file is hard-linked.
+ * @returns `'written'` when a snapshot file was written; `'linked'` when the
+ *          same physical database was already snapshotted in this run and the
+ *          file was hard-linked under this prefix; `'absent'` when the
+ *          database does not exist in this project (or is a derived row).
+ *          Opener, ownership and `VACUUM INTO` errors throw.
  *
  * @task T10316 — eager-open via openCleoDb chokepoint (Saga T10281 / E3)
  * @task T10317 — raw-file-vacuum-readonly strategy for opener-less roles
+ * @task T12508 — reports whether it wrote, so the gate never records a skip as a snapshot
  */
-async function snapshotOne(target, backupDir, now, cwd) {
+async function snapshotOne(target, backupDir, writtenBySource, cwd) {
     if (target.strategy === 'skip-derived') {
         // Derived row — file is rebuildable from the blob CAS. Inventory row
         // documents `backupPath === 'rebuildable-from-blob-store'`. Nothing to do.
-        return;
+        return 'absent';
     }
-    let db = target.getDb();
+    let db = target.getDb(cwd);
     let opened = null;
     if (!db) {
         // T10316 / T10317: eager-open via the canonical per-DB chokepoint (for
@@ -500,19 +764,59 @@ async function snapshotOne(target, backupDir, now, cwd) {
         // raw-file-vacuum-readonly roles). Either way, the snapshot pipeline
         // never silently skips a registered target just because the in-process
         // handle cache is empty.
+        // An opener that THROWS (locked file, malformed orphan) propagates: the
+        // gate reports it as failed. `null` means there is no such database here.
+        db = await target.openDb(cwd);
+        if (!db)
+            return 'absent';
+        opened = db;
+    }
+    let destName;
+    let source;
+    try {
+        source = sourceFileOf(db);
+        if (source !== null && (target.tier === 'project' || target.tier === 'derived')) {
+            assertOwnedByProject(source, target.prefix, cwd);
+        }
+        destName = await freeSnapshotName(backupDir, target.prefix);
+    }
+    catch (err) {
+        if (opened && target.closeDb)
+            target.closeDb(opened);
+        throw err;
+    }
+    const dest = join(backupDir, destName);
+    // Leftovers of a snapshot killed mid-write (see commitSnapshotFile).
+    removeDeadTempSnapshots(backupDir);
+    // Already snapshotted this physical file in this run: hard-link the same
+    // snapshot under this prefix. One VACUUM, no extra disk, and every reader
+    // that looks for `<prefix>-*.db` (restore, recover-brain-db, listing)
+    // still finds a file. A filesystem without hard links (exFAT, FAT, some
+    // network mounts) gets a copy instead.
+    const existing = source !== null ? writtenBySource.get(source) : undefined;
+    if (existing !== undefined) {
         try {
-            db = await target.openDb(cwd);
+            if (tryHardLink(existing, dest)) {
+                rotateSnapshots(backupDir, target.prefix, destName);
+                return 'linked';
+            }
+            const tmp = tempSnapshotPath(dest);
+            try {
+                copyFileSync(existing, tmp);
+                commitSnapshotFile(tmp, dest);
+            }
+            catch (err) {
+                rmSync(tmp, { force: true });
+                throw err;
+            }
+            rotateSnapshots(backupDir, target.prefix, destName);
+            return 'written';
         }
-        catch {
-            // Non-fatal — opener failure (e.g. missing project context, locked
-            // file, malformed orphan) must not block snapshots of other targets.
-            return;
+        finally {
+            if (opened && target.closeDb)
+                target.closeDb(opened);
         }
-        if (!db)
-            return;
-        opened = db;
     }
-    const dest = join(backupDir, `${target.prefix}-${formatTimestamp(now)}.db`);
     try {
         // TRUNCATE checkpoint: flushes all WAL frames to the main DB and truncates
         // the WAL file to zero bytes, ensuring a consistent DB state before the
@@ -520,10 +824,23 @@ async function snapshotOne(target, backupDir, now, cwd) {
         // of orphan files there is no WAL to truncate, but the pragma is a no-op
         // in that case so we keep the call uniform.
         db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-        rotateSnapshots(backupDir, target.prefix);
-        // Escape single quotes in path (path is programmatic, but be safe).
-        const safeDest = dest.replace(/'/g, "''");
-        db.exec(`VACUUM INTO '${safeDest}'`);
+        // VACUUM INTO a temp name, fsync, then rename: a process killed
+        // mid-VACUUM leaves only `<name>.tmp-<pid>`, which no reader lists,
+        // never an empty file under a valid snapshot name (T12508).
+        const tmp = tempSnapshotPath(dest);
+        try {
+            // Escape single quotes in path (path is programmatic, but be safe).
+            db.exec(`VACUUM INTO '${tmp.replace(/'/g, "''")}'`);
+            commitSnapshotFile(tmp, dest);
+        }
+        catch (err) {
+            rmSync(tmp, { force: true });
+            throw err;
+        }
+        if (source !== null)
+            writtenBySource.set(source, dest);
+        rotateSnapshots(backupDir, target.prefix, destName);
+        return 'written';
     }
     finally {
         // Release the ephemeral handle for raw-file-vacuum-readonly targets.
@@ -537,42 +854,40 @@ async function snapshotOne(target, backupDir, now, cwd) {
 /**
  * Create a VACUUM INTO snapshot of the primary SQLite database (tasks.db).
  *
- * Debounced by default (30s). Pass `force: true` to bypass debounce. This
- * function is retained for backward compatibility with existing call sites
- * in `data-safety-central.ts` that only snapshot tasks.db.
- *
- * Prefer {@link vacuumIntoBackupAll} for new code — it snapshots every
- * inventory-registered database and shares the same debounce + rotation
- * guarantees.
+ * Retained for backward compatibility with call sites in
+ * `data-safety-central.ts` that only snapshot tasks.db. It passes through the
+ * same project-wide gate as {@link vacuumIntoBackupAll}: at most one snapshot
+ * in flight per project. Per-write checkpoints use the debounced `routine`
+ * mode; pre-destructive checkpoints pass `mode: 'required'` and AWAIT the
+ * result, so the snapshot is on disk before the destructive step begins.
  *
  * Non-fatal: all errors are swallowed — backup failure must never
  * interrupt normal operation.
+ *
+ * @returns The gate outcome (which prefixes were snapshotted, or why none
+ *          were), or `null` when nothing could be attempted.
+ * @task T12508 — gated; the `force` bypass was removed
  */
 export async function vacuumIntoBackup(opts = {}) {
-    const now = Date.now();
-    const prefix = 'tasks';
-    const last = _lastBackupEpoch[prefix] ?? 0;
-    if (!opts.force && now - last < DEBOUNCE_MS) {
-        return; // debounced
-    }
     try {
-        const cleoDir = getCleoDir(opts.cwd);
-        const backupDir = join(cleoDir, 'backups', 'sqlite');
-        mkdirSync(backupDir, { recursive: true });
-        const target = SNAPSHOT_TARGETS.find((t) => t.prefix === prefix);
+        const target = SNAPSHOT_TARGETS.find((t) => t.prefix === 'tasks');
         if (!target)
-            return;
-        await snapshotOne(target, backupDir, new Date(), opts.cwd);
-        _lastBackupEpoch[prefix] = Date.now();
+            return null;
+        return await snapshotProjectTargetsGated([target], opts);
     }
     catch {
         // non-fatal — backup failure must never interrupt normal operation
+        return null;
     }
 }
 /**
  * Create VACUUM INTO snapshots of every project-tier (and opt-in `derived`)
- * SQLite database registered in `DB_INVENTORY`. Each database is debounced
- * independently.
+ * SQLite database registered in `DB_INVENTORY`, through the project-wide
+ * cross-process gate (see `snapshot-gate.ts`). The session-end hook passes
+ * `mode: 'required'`: the snapshot is not debounced by earlier per-write
+ * checkpoints, so it captures the session's final writes, and requests that
+ * queue behind one running snapshot are all covered by the next one — a burst
+ * of session ends produces one snapshot.
  *
  * This is the preferred entry point for session-lifecycle hooks and
  * pre-destructive-operation snapshots — it guarantees that BRAIN memory is
@@ -587,33 +902,17 @@ export async function vacuumIntoBackup(opts = {}) {
  *
  * @task T5158
  * @task T10317 — extended to every `DB_INVENTORY` project + derived row
+ * @returns The gate outcome (which prefixes were snapshotted, or why none
+ *          were), or `null` when nothing could be attempted.
+ * @task T12508 — cross-process gate + persisted debounce; `force` removed
  */
 export async function vacuumIntoBackupAll(opts = {}) {
-    const nowMs = Date.now();
-    const now = new Date();
-    let backupDir;
     try {
-        const cleoDir = getCleoDir(opts.cwd);
-        backupDir = join(cleoDir, 'backups', 'sqlite');
-        mkdirSync(backupDir, { recursive: true });
+        return await snapshotProjectTargetsGated(SNAPSHOT_TARGETS, opts);
     }
     catch {
-        return; // cannot resolve backup dir — abort silently
-    }
-    for (const target of SNAPSHOT_TARGETS) {
-        if (target.strategy === 'skip-derived')
-            continue;
-        const last = _lastBackupEpoch[target.prefix] ?? 0;
-        if (!opts.force && nowMs - last < DEBOUNCE_MS) {
-            continue; // debounced — skip this target only
-        }
-        try {
-            await snapshotOne(target, backupDir, now, opts.cwd);
-            _lastBackupEpoch[target.prefix] = Date.now();
-        }
-        catch {
-            // non-fatal — continue with remaining targets
-        }
+        // non-fatal — backup failure must never interrupt normal operation
+        return null;
     }
 }
 /**
@@ -774,11 +1073,20 @@ export async function vacuumIntoGlobalBackup(dbName, opts) {
     catch {
         // non-fatal — continue even if rotation enumeration fails
     }
+    removeDeadTempSnapshots(backupDir);
     try {
-        // Checkpoint then VACUUM INTO for a WAL-free, atomic snapshot.
+        // Checkpoint then VACUUM INTO a temp name, fsync, rename (T12508): a
+        // kill mid-VACUUM never leaves an empty file under a snapshot name.
         db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-        const safeDest = snapshotPath.replace(/'/g, "''");
-        db.exec(`VACUUM INTO '${safeDest}'`);
+        const tmp = tempSnapshotPath(snapshotPath);
+        try {
+            db.exec(`VACUUM INTO '${tmp.replace(/'/g, "''")}'`);
+            commitSnapshotFile(tmp, snapshotPath);
+        }
+        catch (err) {
+            rmSync(tmp, { force: true });
+            throw err;
+        }
     }
     finally {
         // Release ephemeral handle for raw-file-vacuum-readonly targets.