@cleocode/core 2026.4.9 → 2026.4.12

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

@@ -1,34 +1,145 @@
 /**
  * SQLite backup via VACUUM INTO with snapshot rotation.
  *
- * Produces self-contained, WAL-free copies of tasks.db into
- * .cleo/backups/sqlite/ with a configurable rotation limit.
- * All errors are swallowed -- backup failure must never interrupt
- * normal operation.
+ * Produces self-contained, WAL-free copies of CLEO SQLite databases
+ * (tasks.db, brain.db at project tier; nexus.db at global tier) into
+ * `.cleo/backups/sqlite/` (project) or `$XDG_DATA_HOME/cleo/backups/sqlite/`
+ * (global) with a configurable rotation limit. All errors are swallowed —
+ * backup failure must never interrupt normal operation.
  *
  * @task T4873
+ * @task T5158 — extended to cover brain.db
+ * @task T306  — extended to cover global-tier nexus.db (epic T299)
  * @epic T4867
  */
+/** Options accepted by {@link vacuumIntoBackup} and {@link vacuumIntoBackupAll}. */
 export interface VacuumOptions {
+    /**
+     * Working directory used to resolve the project-local `.cleo/backups/sqlite/`
+     * directory. Defaults to `process.cwd()` (delegated to {@link getCleoDir}).
+     */
     cwd?: string;
+    /** When true, bypass the {@link DEBOUNCE_MS} debounce window. */
     force?: boolean;
 }
 /**
- * Create a VACUUM INTO snapshot of the SQLite database.
+ * Create a VACUUM INTO snapshot of the primary SQLite database (tasks.db).
  *
- * Debounced by default (30s). Pass `force: true` to bypass debounce.
- * WAL checkpoint is run before the snapshot for consistency.
- * Oldest snapshots are rotated out when MAX_SNAPSHOTS is reached.
+ * Debounced by default (30s). Pass `force: true` to bypass debounce. This
+ * function is retained for backward compatibility with existing call sites
+ * in `data-safety.ts` / `data-safety-central.ts` that only snapshot tasks.db.
  *
- * Non-fatal: all errors are swallowed.
+ * Prefer {@link vacuumIntoBackupAll} for new code — it snapshots every
+ * registered database (currently tasks.db + brain.db) and shares the same
+ * debounce + rotation guarantees.
+ *
+ * Non-fatal: all errors are swallowed — backup failure must never
+ * interrupt normal operation.
  */
 export declare function vacuumIntoBackup(opts?: VacuumOptions): Promise<void>;
 /**
- * List existing SQLite backup snapshots, newest first.
+ * Create VACUUM INTO snapshots of all registered CLEO SQLite databases
+ * (currently tasks.db + brain.db). Each database is debounced independently.
+ *
+ * This is the preferred entry point for session-lifecycle hooks and
+ * pre-destructive-operation snapshots — it guarantees that BRAIN memory is
+ * snapshotted alongside task state.
+ *
+ * Non-fatal: errors are swallowed per database so a brain.db failure cannot
+ * block a tasks.db snapshot (and vice versa).
+ */
+export declare function vacuumIntoBackupAll(opts?: VacuumOptions): Promise<void>;
+/**
+ * List existing tasks.db snapshots (newest first).
+ *
+ * Retained for backward compatibility. For new code prefer
+ * {@link listSqliteBackupsAll}.
  */
 export declare function listSqliteBackups(cwd?: string): Array<{
     name: string;
     path: string;
     mtimeMs: number;
 }>;
+/**
+ * List existing brain.db snapshots (newest first).
+ */
+export declare function listBrainBackups(cwd?: string): Array<{
+    name: string;
+    path: string;
+    mtimeMs: number;
+}>;
+/**
+ * Aggregated listing of all registered SQLite snapshots.
+ *
+ * Returns an object keyed by snapshot prefix (`tasks`, `brain`) where each
+ * value is the per-prefix list sorted newest-first. Missing prefixes are
+ * represented as empty arrays.
+ */
+export declare function listSqliteBackupsAll(cwd?: string): Record<string, Array<{
+    name: string;
+    path: string;
+    mtimeMs: number;
+}>>;
+/**
+ * Backup scope: project (per-project `.cleo/`) or global (`$XDG_DATA_HOME/cleo/`).
+ *
+ * @task T306
+ * @epic T299
+ */
+export type BackupScope = 'project' | 'global';
+/**
+ * Snapshot a global-tier SQLite database via VACUUM INTO.
+ *
+ * Writes to `$XDG_DATA_HOME/cleo/backups/sqlite/<dbName>-YYYYMMDD-HHmmss.db`
+ * and enforces a per-prefix rotation window (default 10 snapshots).
+ *
+ * Non-fatal: errors from any individual step are surfaced via the return value
+ * but never thrown — a failed snapshot MUST NOT interrupt normal operation.
+ *
+ * @param dbName         - Which global-tier DB to snapshot (`'nexus'`; `'signaldock'` reserved for T310)
+ * @param opts.rotation  - Maximum retained snapshots per prefix (default 10)
+ * @param opts.cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ * @returns Object containing the new snapshot path and any rotated (deleted) file paths
+ *
+ * @task T306
+ * @epic T299
+ * @why ADR-036 §Backup Mechanism requires VACUUM INTO rotation at the global tier;
+ *      nexus.db has zero backup coverage prior to v2026.4.11.
+ */
+export declare function vacuumIntoGlobalBackup(dbName: 'nexus' | 'signaldock', opts?: {
+    rotation?: number;
+    cleoHomeOverride?: string;
+}): Promise<{
+    snapshotPath: string;
+    rotated: string[];
+}>;
+/**
+ * A single entry returned by {@link listGlobalSqliteBackups}.
+ *
+ * @task T306
+ * @epic T299
+ */
+export interface GlobalBackupEntry {
+    /** Snapshot filename, e.g. `nexus-20260408-143022.db`. */
+    name: string;
+    /** Absolute path to the snapshot file. */
+    path: string;
+    /** File size in bytes. */
+    size: number;
+    /** Last-modified timestamp. */
+    mtime: Date;
+}
+/**
+ * List global-tier SQLite backups from `$XDG_DATA_HOME/cleo/backups/sqlite/`,
+ * optionally filtered by prefix (e.g. `'nexus'`). Sorted newest-first by mtime.
+ *
+ * Returns an empty array when the backup directory does not exist.
+ *
+ * @param prefix            - Optional prefix filter; when omitted all `.db` snapshot files are listed
+ * @param cleoHomeOverride  - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ *
+ * @task T306
+ * @epic T299
+ */
+export declare function listGlobalSqliteBackups(prefix?: string, cleoHomeOverride?: string): GlobalBackupEntry[];
 //# sourceMappingURL=sqlite-backup.d.ts.map

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":"AAAA;;;;;;;;;;GAUG;AAwCH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmC9E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAiBxD"}
+{"version":3,"file":"sqlite-backup.d.ts","sourceRoot":"","sources":["../../src/store/sqlite-backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6FH,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB9E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBjF;AA8BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAExD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAMxE;AAQD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAmB/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,OAAO,GAAG,YAAY,EAC9B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsDtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,MAAM,GACxB,iBAAiB,EAAE,CAkBrB"}

package/dist/store/sqlite-backup.js

@@ -0,0 +1,359 @@
+/**
+ * SQLite backup via VACUUM INTO with snapshot rotation.
+ *
+ * Produces self-contained, WAL-free copies of CLEO SQLite databases
+ * (tasks.db, brain.db at project tier; nexus.db at global tier) into
+ * `.cleo/backups/sqlite/` (project) or `$XDG_DATA_HOME/cleo/backups/sqlite/`
+ * (global) with a configurable rotation limit. All errors are swallowed —
+ * backup failure must never interrupt normal operation.
+ *
+ * @task T4873
+ * @task T5158 — extended to cover brain.db
+ * @task T306  — extended to cover global-tier nexus.db (epic T299)
+ * @epic T4867
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCleoDir, getCleoHome } from '../paths.js';
+import { getBrainNativeDb } from './brain-sqlite.js';
+import { getNexusNativeDb } from './nexus-sqlite.js';
+import { 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"`).
+ */
+const _lastBackupEpoch = {};
+/**
+ * Canonical list of snapshot targets. Ordering is insertion order — tasks.db
+ * snapshots first (highest-value operational state), then brain.db.
+ */
+const SNAPSHOT_TARGETS = [
+    { prefix: 'tasks', getDb: getNativeDb },
+    { prefix: 'brain', getDb: getBrainNativeDb },
+];
+/**
+ * Format a Date as `YYYYMMDD-HHmmss` (local time) for snapshot filenames.
+ *
+ * Matches the regex `/^(?:tasks|brain)-\d{8}-\d{6}\.db$/` used by the rotation
+ * and listing logic below.
+ */
+function formatTimestamp(d) {
+    const pad = (n, len = 2) => String(n).padStart(len, '0');
+    return (`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+        `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`);
+}
+/**
+ * Build the regex that matches snapshot filenames for the given prefix.
+ * Isolated so both {@link rotateSnapshots} and {@link listSqliteBackupsForPrefix}
+ * share a single source of truth.
+ */
+function snapshotPattern(prefix) {
+    // Escape the prefix in case it ever contains regex metacharacters.
+    const safe = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    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.
+ */
+function rotateSnapshots(backupDir, prefix) {
+    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);
+        }
+    }
+    catch {
+        // non-fatal
+    }
+}
+/**
+ * Create a VACUUM INTO snapshot of a single SQLite database.
+ *
+ * Runs `PRAGMA wal_checkpoint(TRUNCATE)` first to flush the WAL for a
+ * consistent snapshot, then issues `VACUUM INTO '<dest>'` which SQLite
+ * implements as an atomic, fully defragmented clone.
+ *
+ * Non-fatal: all errors are swallowed via the outer try in
+ * {@link vacuumIntoBackupAll}; failures here must never block normal
+ * operation.
+ *
+ * @param target — snapshot target descriptor (prefix + native DB getter)
+ * @param backupDir — absolute path to `.cleo/backups/sqlite/`
+ * @param now — reference timestamp for the filename
+ */
+function snapshotOne(target, backupDir, now) {
+    const db = target.getDb();
+    if (!db)
+        return; // DB not initialized in this process — skip silently
+    const dest = join(backupDir, `${target.prefix}-${formatTimestamp(now)}.db`);
+    // 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
+    // VACUUM INTO snapshot (ADR-013, section 3 point 7). This is safe because
+    // the .db files are excluded from project git tracking (.gitignore + git
+    // rm --cached), so git operations cannot restore a stale WAL. The root
+    // cause of the 2026-02-25 data loss was that WAL files were still tracked
+    // in the project git index; that has been resolved (T4894, T5158).
+    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}'`);
+}
+/**
+ * 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.ts` / `data-safety-central.ts` that only snapshot tasks.db.
+ *
+ * Prefer {@link vacuumIntoBackupAll} for new code — it snapshots every
+ * registered database (currently tasks.db + brain.db) and shares the same
+ * debounce + rotation guarantees.
+ *
+ * Non-fatal: all errors are swallowed — backup failure must never
+ * interrupt normal operation.
+ */
+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);
+        if (!target)
+            return;
+        snapshotOne(target, backupDir, new Date());
+        _lastBackupEpoch[prefix] = Date.now();
+    }
+    catch {
+        // non-fatal — backup failure must never interrupt normal operation
+    }
+}
+/**
+ * Create VACUUM INTO snapshots of all registered CLEO SQLite databases
+ * (currently tasks.db + brain.db). Each database is debounced independently.
+ *
+ * This is the preferred entry point for session-lifecycle hooks and
+ * pre-destructive-operation snapshots — it guarantees that BRAIN memory is
+ * snapshotted alongside task state.
+ *
+ * Non-fatal: errors are swallowed per database so a brain.db failure cannot
+ * block a tasks.db snapshot (and vice versa).
+ */
+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 });
+    }
+    catch {
+        return; // cannot resolve backup dir — abort silently
+    }
+    for (const target of SNAPSHOT_TARGETS) {
+        const last = _lastBackupEpoch[target.prefix] ?? 0;
+        if (!opts.force && nowMs - last < DEBOUNCE_MS) {
+            continue; // debounced — skip this target only
+        }
+        try {
+            snapshotOne(target, backupDir, now);
+            _lastBackupEpoch[target.prefix] = Date.now();
+        }
+        catch {
+            // non-fatal — continue with remaining targets
+        }
+    }
+}
+/**
+ * List existing snapshots for a given prefix (`"tasks"` or `"brain"`),
+ * newest first. Returns an empty array if the backup directory does not
+ * exist.
+ */
+function listSqliteBackupsForPrefix(prefix, cwd) {
+    try {
+        const cleoDir = getCleoDir(cwd);
+        const backupDir = join(cleoDir, 'backups', 'sqlite');
+        if (!existsSync(backupDir))
+            return [];
+        const pattern = snapshotPattern(prefix);
+        return readdirSync(backupDir)
+            .filter((f) => pattern.test(f))
+            .map((f) => ({
+            name: f,
+            path: join(backupDir, f),
+            mtimeMs: statSync(join(backupDir, f)).mtimeMs,
+        }))
+            .sort((a, b) => b.mtimeMs - a.mtimeMs); // newest first
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List existing tasks.db snapshots (newest first).
+ *
+ * Retained for backward compatibility. For new code prefer
+ * {@link listSqliteBackupsAll}.
+ */
+export function listSqliteBackups(cwd) {
+    return listSqliteBackupsForPrefix('tasks', cwd);
+}
+/**
+ * List existing brain.db snapshots (newest first).
+ */
+export function listBrainBackups(cwd) {
+    return listSqliteBackupsForPrefix('brain', cwd);
+}
+/**
+ * Aggregated listing of all registered SQLite snapshots.
+ *
+ * Returns an object keyed by snapshot prefix (`tasks`, `brain`) where each
+ * value is the per-prefix list sorted newest-first. Missing prefixes are
+ * represented as empty arrays.
+ */
+export function listSqliteBackupsAll(cwd) {
+    const out = {};
+    for (const target of SNAPSHOT_TARGETS) {
+        out[target.prefix] = listSqliteBackupsForPrefix(target.prefix, cwd);
+    }
+    return out;
+}
+/**
+ * Registered global-tier snapshot targets. `signaldock` is reserved for T310
+ * — only `nexus` is active in v2026.4.11.
+ */
+const GLOBAL_SNAPSHOT_TARGETS = [{ prefix: 'nexus', getDb: getNexusNativeDb }];
+/**
+ * Resolve the global-tier backup directory, creating it on first use.
+ *
+ * Uses `cleoHomeOverride` when provided (test isolation) or falls back to
+ * `getCleoHome()` (XDG-compliant; never hardcodes `~/.cleo`).
+ */
+function resolveGlobalBackupDir(cleoHomeOverride) {
+    const base = cleoHomeOverride ?? getCleoHome();
+    return join(base, 'backups', 'sqlite');
+}
+/**
+ * Snapshot a global-tier SQLite database via VACUUM INTO.
+ *
+ * Writes to `$XDG_DATA_HOME/cleo/backups/sqlite/<dbName>-YYYYMMDD-HHmmss.db`
+ * and enforces a per-prefix rotation window (default 10 snapshots).
+ *
+ * Non-fatal: errors from any individual step are surfaced via the return value
+ * but never thrown — a failed snapshot MUST NOT interrupt normal operation.
+ *
+ * @param dbName         - Which global-tier DB to snapshot (`'nexus'`; `'signaldock'` reserved for T310)
+ * @param opts.rotation  - Maximum retained snapshots per prefix (default 10)
+ * @param opts.cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ * @returns Object containing the new snapshot path and any rotated (deleted) file paths
+ *
+ * @task T306
+ * @epic T299
+ * @why ADR-036 §Backup Mechanism requires VACUUM INTO rotation at the global tier;
+ *      nexus.db has zero backup coverage prior to v2026.4.11.
+ */
+export async function vacuumIntoGlobalBackup(dbName, opts) {
+    const maxSnaps = opts?.rotation ?? MAX_SNAPSHOTS;
+    const backupDir = resolveGlobalBackupDir(opts?.cleoHomeOverride);
+    mkdirSync(backupDir, { recursive: true });
+    const target = GLOBAL_SNAPSHOT_TARGETS.find((t) => t.prefix === dbName);
+    if (!target) {
+        return { snapshotPath: '', rotated: [] };
+    }
+    const db = target.getDb();
+    if (!db) {
+        return { snapshotPath: '', rotated: [] };
+    }
+    const now = new Date();
+    const snapshotName = `${dbName}-${formatTimestamp(now)}.db`;
+    const snapshotPath = join(backupDir, snapshotName);
+    // Collect files that will be rotated out before writing the new one.
+    const rotated = [];
+    try {
+        const pattern = snapshotPattern(dbName);
+        const existing = 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
+        // Remove oldest until we have room for the new snapshot.
+        while (existing.length >= maxSnaps) {
+            const oldest = existing.shift();
+            if (!oldest)
+                break;
+            try {
+                unlinkSync(oldest.path);
+                rotated.push(oldest.path);
+            }
+            catch {
+                // non-fatal rotation failure
+            }
+        }
+    }
+    catch {
+        // non-fatal — continue even if rotation enumeration fails
+    }
+    // Checkpoint then VACUUM INTO for a WAL-free, atomic snapshot.
+    db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    const safeDest = snapshotPath.replace(/'/g, "''");
+    db.exec(`VACUUM INTO '${safeDest}'`);
+    return { snapshotPath, rotated };
+}
+/**
+ * List global-tier SQLite backups from `$XDG_DATA_HOME/cleo/backups/sqlite/`,
+ * optionally filtered by prefix (e.g. `'nexus'`). Sorted newest-first by mtime.
+ *
+ * Returns an empty array when the backup directory does not exist.
+ *
+ * @param prefix            - Optional prefix filter; when omitted all `.db` snapshot files are listed
+ * @param cleoHomeOverride  - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ *
+ * @task T306
+ * @epic T299
+ */
+export function listGlobalSqliteBackups(prefix, cleoHomeOverride) {
+    try {
+        const backupDir = resolveGlobalBackupDir(cleoHomeOverride);
+        if (!existsSync(backupDir))
+            return [];
+        const pattern = prefix ? snapshotPattern(prefix) : /^[a-zA-Z0-9_-]+-\d{8}-\d{6}\.db$/;
+        return readdirSync(backupDir)
+            .filter((f) => pattern.test(f))
+            .map((f) => {
+            const filePath = join(backupDir, f);
+            const s = statSync(filePath);
+            return { name: f, path: filePath, size: s.size, mtime: new Date(s.mtimeMs) };
+        })
+            .sort((a, b) => b.mtime.getTime() - a.mtime.getTime()); // newest first
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=sqlite-backup.js.map

package/dist/store/sqlite-backup.js.map

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