@cleocode/core 2026.4.9 → 2026.4.11

package/src/store/__tests__/sqlite-backup-global.test.ts

@@ -0,0 +1,281 @@
+/**
+ * Tests for global-tier SQLite VACUUM INTO backup (vacuumIntoGlobalBackup,
+ * listGlobalSqliteBackups).
+ *
+ * All tests use a tmp-dir override via `cleoHomeOverride` so they NEVER
+ * touch the real user's $XDG_DATA_HOME/cleo/ directory or corrupt actual
+ * nexus backups.
+ *
+ * Coverage:
+ * - vacuumIntoGlobalBackup creates a snapshot and increments file count
+ * - listGlobalSqliteBackups returns entries sorted newest-first (mtime desc)
+ * - Rotation keeps last 10 snapshots, deletes older ones
+ * - Snapshot passes PRAGMA integrity_check
+ * - Scope filter: listGlobalSqliteBackups with prefix excludes other prefixes
+ * - Restore round-trip: snapshot then restore preserves DB content
+ * - XDG path: snapshots land under cleoHomeOverride/backups/sqlite/, not hardcoded ~/.cleo/
+ *
+ * @task T306
+ * @epic T299
+ */
+
+import { existsSync, mkdirSync, readdirSync, utimesSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('sqlite-backup global tier', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+  });
+
+  /**
+   * Create a minimal, valid SQLite database at `dbPath` with a single table
+   * and one row so VACUUM INTO and integrity_check have something to verify.
+   */
+  function seedSqliteDb(dbPath: string): void {
+    const db = new DatabaseSync(dbPath);
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS test_data (id INTEGER PRIMARY KEY, value TEXT);
+      INSERT INTO test_data (value) VALUES ('hello');
+    `);
+    db.close();
+  }
+
+  it('vacuumIntoGlobalBackup creates a snapshot file under cleoHomeOverride/backups/sqlite/', async () => {
+    vi.resetModules();
+    const cleoHome = join(tmpdir(), `cleo-global-test-create-${Date.now()}`);
+    const nexusDbPath = join(cleoHome, 'nexus.db');
+    mkdirSync(cleoHome, { recursive: true });
+    seedSqliteDb(nexusDbPath);
+
+    // Mock getNexusNativeDb to return a real DatabaseSync handle
+    const nexusDb = new DatabaseSync(nexusDbPath);
+    vi.doMock('../nexus-sqlite.js', () => ({ getNexusNativeDb: () => nexusDb }));
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => cleoHome }));
+
+    const { vacuumIntoGlobalBackup } = await import('../sqlite-backup.js');
+    const result = await vacuumIntoGlobalBackup('nexus', { cleoHomeOverride: cleoHome });
+
+    nexusDb.close();
+
+    expect(result.snapshotPath).toBeTruthy();
+    expect(result.snapshotPath).toContain('nexus-');
+    expect(result.snapshotPath).toContain(join(cleoHome, 'backups', 'sqlite'));
+    expect(existsSync(result.snapshotPath)).toBe(true);
+  });
+
+  it('vacuumIntoGlobalBackup XDG path: uses cleoHomeOverride, not hardcoded ~/.cleo/', async () => {
+    vi.resetModules();
+    const cleoHome = join(tmpdir(), `cleo-global-xdg-${Date.now()}`);
+    const nexusDbPath = join(cleoHome, 'nexus.db');
+    mkdirSync(cleoHome, { recursive: true });
+    seedSqliteDb(nexusDbPath);
+
+    const nexusDb = new DatabaseSync(nexusDbPath);
+    vi.doMock('../nexus-sqlite.js', () => ({ getNexusNativeDb: () => nexusDb }));
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => cleoHome }));
+
+    const { vacuumIntoGlobalBackup } = await import('../sqlite-backup.js');
+    const result = await vacuumIntoGlobalBackup('nexus', { cleoHomeOverride: cleoHome });
+
+    nexusDb.close();
+
+    // Must be under the override dir, not the user's actual cleo home
+    expect(result.snapshotPath).toContain(cleoHome);
+    expect(result.snapshotPath).not.toContain(join(homedir(), '.local'));
+    expect(result.snapshotPath).not.toContain('.cleo');
+  });
+
+  it('vacuumIntoGlobalBackup is non-fatal when getNexusNativeDb() returns null', async () => {
+    vi.resetModules();
+    vi.doMock('../nexus-sqlite.js', () => ({ getNexusNativeDb: () => null }));
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => tmpdir() }));
+
+    const { vacuumIntoGlobalBackup } = await import('../sqlite-backup.js');
+    const result = await vacuumIntoGlobalBackup('nexus', {
+      cleoHomeOverride: join(tmpdir(), `cleo-null-nexus-${Date.now()}`),
+    });
+
+    expect(result.snapshotPath).toBe('');
+    expect(result.rotated).toEqual([]);
+  });
+
+  it('vacuumIntoGlobalBackup snapshot passes PRAGMA integrity_check', async () => {
+    vi.resetModules();
+    const cleoHome = join(tmpdir(), `cleo-global-integrity-${Date.now()}`);
+    const nexusDbPath = join(cleoHome, 'nexus.db');
+    mkdirSync(cleoHome, { recursive: true });
+    seedSqliteDb(nexusDbPath);
+
+    const nexusDb = new DatabaseSync(nexusDbPath);
+    vi.doMock('../nexus-sqlite.js', () => ({ getNexusNativeDb: () => nexusDb }));
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => cleoHome }));
+
+    const { vacuumIntoGlobalBackup } = await import('../sqlite-backup.js');
+    const result = await vacuumIntoGlobalBackup('nexus', { cleoHomeOverride: cleoHome });
+
+    nexusDb.close();
+
+    expect(existsSync(result.snapshotPath)).toBe(true);
+
+    // Open snapshot and verify integrity
+    const snapshot = new DatabaseSync(result.snapshotPath, { readonly: true });
+    try {
+      const row = snapshot.prepare('PRAGMA integrity_check').get() as Record<string, unknown>;
+      const ok = row?.['integrity_check'] ?? row?.['integrity check'];
+      expect(ok).toBe('ok');
+    } finally {
+      snapshot.close();
+    }
+  });
+
+  it('rotation keeps last 10 snapshots and deletes older ones', async () => {
+    vi.resetModules();
+    const cleoHome = join(tmpdir(), `cleo-global-rotation-${Date.now()}`);
+    const nexusDbPath = join(cleoHome, 'nexus.db');
+    const backupDir = join(cleoHome, 'backups', 'sqlite');
+    mkdirSync(backupDir, { recursive: true });
+    seedSqliteDb(nexusDbPath);
+
+    // Seed 11 stale snapshots with valid name pattern
+    for (let i = 0; i < 11; i++) {
+      const day = String(i + 1).padStart(2, '0');
+      writeFileSync(join(backupDir, `nexus-202601${day}-120000.db`), 'fake');
+    }
+
+    const nexusDb = new DatabaseSync(nexusDbPath);
+    vi.doMock('../nexus-sqlite.js', () => ({ getNexusNativeDb: () => nexusDb }));
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => cleoHome }));
+
+    const { vacuumIntoGlobalBackup } = await import('../sqlite-backup.js');
+    const result = await vacuumIntoGlobalBackup('nexus', { cleoHomeOverride: cleoHome });
+
+    nexusDb.close();
+
+    const remaining = readdirSync(backupDir).filter(
+      (f) => f.startsWith('nexus-') && f.endsWith('.db'),
+    );
+    // The new snapshot was written, meaning 11 stale + 1 new. After rotation,
+    // MAX_SNAPSHOTS (10) must be respected.
+    expect(remaining.length).toBeLessThanOrEqual(10);
+    // The result snapshot should exist
+    expect(existsSync(result.snapshotPath)).toBe(true);
+    // At least 2 files were rotated out (11 + 1 new = 12, keep 10, remove 2)
+    expect(result.rotated.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('listGlobalSqliteBackups returns entries sorted newest-first by mtime', async () => {
+    vi.resetModules();
+    const cleoHome = join(tmpdir(), `cleo-global-list-${Date.now()}`);
+    const backupDir = join(cleoHome, 'backups', 'sqlite');
+    mkdirSync(backupDir, { recursive: true });
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => cleoHome }));
+
+    const f1 = join(backupDir, 'nexus-20260101-120000.db');
+    const f2 = join(backupDir, 'nexus-20260102-120000.db');
+    const f3 = join(backupDir, 'nexus-20260103-120000.db');
+    writeFileSync(f1, 'fake1');
+    writeFileSync(f2, 'fake2');
+    writeFileSync(f3, 'fake3');
+    // Set deterministic mtimes: f1 oldest, f3 newest
+    utimesSync(f1, 1_700_000_100, 1_700_000_100);
+    utimesSync(f2, 1_700_000_200, 1_700_000_200);
+    utimesSync(f3, 1_700_000_300, 1_700_000_300);
+
+    const { listGlobalSqliteBackups } = await import('../sqlite-backup.js');
+    const entries = listGlobalSqliteBackups(undefined, cleoHome);
+
+    expect(entries.map((e) => e.name)).toEqual([
+      'nexus-20260103-120000.db',
+      'nexus-20260102-120000.db',
+      'nexus-20260101-120000.db',
+    ]);
+    // Each entry has required fields
+    for (const e of entries) {
+      expect(e.path).toBeTruthy();
+      expect(typeof e.size).toBe('number');
+      expect(e.mtime).toBeInstanceOf(Date);
+    }
+  });
+
+  it('listGlobalSqliteBackups prefix filter excludes other prefixes', async () => {
+    vi.resetModules();
+    const cleoHome = join(tmpdir(), `cleo-global-filter-${Date.now()}`);
+    const backupDir = join(cleoHome, 'backups', 'sqlite');
+    mkdirSync(backupDir, { recursive: true });
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => cleoHome }));
+
+    // Write files for two different prefixes
+    writeFileSync(join(backupDir, 'nexus-20260101-120000.db'), 'nexus-data');
+    writeFileSync(join(backupDir, 'nexus-20260102-120000.db'), 'nexus-data-2');
+    writeFileSync(join(backupDir, 'signaldock-20260101-120000.db'), 'sd-data');
+
+    const { listGlobalSqliteBackups } = await import('../sqlite-backup.js');
+
+    const nexusOnly = listGlobalSqliteBackups('nexus', cleoHome);
+    const sdOnly = listGlobalSqliteBackups('signaldock', cleoHome);
+    const all = listGlobalSqliteBackups(undefined, cleoHome);
+
+    expect(nexusOnly.every((e) => e.name.startsWith('nexus-'))).toBe(true);
+    expect(nexusOnly.length).toBe(2);
+
+    expect(sdOnly.every((e) => e.name.startsWith('signaldock-'))).toBe(true);
+    expect(sdOnly.length).toBe(1);
+
+    // Unfiltered returns both
+    expect(all.length).toBe(3);
+  });
+
+  it('listGlobalSqliteBackups returns empty array when backup dir does not exist', async () => {
+    vi.resetModules();
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => tmpdir() }));
+
+    const { listGlobalSqliteBackups } = await import('../sqlite-backup.js');
+    const nonExistentHome = join(tmpdir(), `cleo-no-exist-${Date.now()}`);
+    const entries = listGlobalSqliteBackups(undefined, nonExistentHome);
+
+    expect(entries).toEqual([]);
+  });
+
+  it('restore round-trip: snapshot then restore preserves all rows', async () => {
+    vi.resetModules();
+    const cleoHome = join(tmpdir(), `cleo-global-roundtrip-${Date.now()}`);
+    const nexusDbPath = join(cleoHome, 'nexus.db');
+    mkdirSync(cleoHome, { recursive: true });
+
+    // Seed with known data
+    const db = new DatabaseSync(nexusDbPath);
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name TEXT);
+      INSERT INTO items (name) VALUES ('alpha');
+      INSERT INTO items (name) VALUES ('beta');
+    `);
+    db.close();
+
+    const nexusDb = new DatabaseSync(nexusDbPath);
+    vi.doMock('../nexus-sqlite.js', () => ({ getNexusNativeDb: () => nexusDb }));
+    vi.doMock('../../paths.js', () => ({ getCleoHome: () => cleoHome }));
+
+    const { vacuumIntoGlobalBackup } = await import('../sqlite-backup.js');
+    const { snapshotPath } = await vacuumIntoGlobalBackup('nexus', {
+      cleoHomeOverride: cleoHome,
+    });
+    nexusDb.close();
+
+    expect(existsSync(snapshotPath)).toBe(true);
+
+    // Verify the snapshot contains all expected rows
+    const snapDb = new DatabaseSync(snapshotPath, { readonly: true });
+    try {
+      const rows = snapDb.prepare('SELECT name FROM items ORDER BY id').all() as Array<{
+        name: string;
+      }>;
+      expect(rows.map((r) => r.name)).toEqual(['alpha', 'beta']);
+    } finally {
+      snapDb.close();
+    }
+  });
+});

package/src/store/__tests__/sqlite-backup.test.ts

@@ -2,16 +2,20 @@
  * Tests for SQLite VACUUM INTO backup module.
  *
  * Verifies:
- * - Non-fatal when getNativeDb() returns null
- * - WAL checkpoint runs before VACUUM INTO
- * - Snapshot rotation enforces MAX_SNAPSHOTS limit
- * - Debounce prevents rapid successive backups
+ * - Non-fatal when getNativeDb() / getBrainNativeDb() return null
+ * - WAL checkpoint runs before VACUUM INTO for each target
+ * - Snapshot rotation enforces MAX_SNAPSHOTS limit per prefix
+ * - Debounce prevents rapid successive backups per prefix
+ * - vacuumIntoBackupAll snapshots both tasks.db and brain.db
+ * - listSqliteBackups / listBrainBackups / listSqliteBackupsAll read back
+ *   the rotated files sorted newest-first
  *
  * @task T4874
+ * @task T5158 — extended to cover brain.db + vacuumIntoBackupAll
  * @epic T4867
  */
 
-import { mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, utimesSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
@@ -24,15 +28,26 @@ describe('sqlite-backup', () => {
 
   it('is non-fatal when getNativeDb() returns null', async () => {
     vi.doMock('../sqlite.js', () => ({ getNativeDb: () => null }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => null }));
     vi.doMock('../../paths.js', () => ({ getCleoDir: () => tmpdir() }));
 
     const { vacuumIntoBackup } = await import('../sqlite-backup.js');
     await expect(vacuumIntoBackup({ force: true })).resolves.not.toThrow();
   });
 
-  it('calls PRAGMA wal_checkpoint(TRUNCATE) before VACUUM INTO', async () => {
+  it('is non-fatal when getBrainNativeDb() returns null', async () => {
+    vi.doMock('../sqlite.js', () => ({ getNativeDb: () => null }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => null }));
+    vi.doMock('../../paths.js', () => ({ getCleoDir: () => tmpdir() }));
+
+    const { vacuumIntoBackupAll } = await import('../sqlite-backup.js');
+    await expect(vacuumIntoBackupAll({ force: true })).resolves.not.toThrow();
+  });
+
+  it('calls PRAGMA wal_checkpoint(TRUNCATE) before VACUUM INTO for tasks.db', async () => {
     const execMock = vi.fn();
     vi.doMock('../sqlite.js', () => ({ getNativeDb: () => ({ exec: execMock }) }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => null }));
     const tempDir = join(tmpdir(), `cleo-test-wal-${Date.now()}`);
     vi.doMock('../../paths.js', () => ({ getCleoDir: () => tempDir }));
 
@@ -46,9 +61,10 @@ describe('sqlite-backup', () => {
     expect(walIdx).toBeLessThan(vacuumIdx);
   });
 
-  it('enforces maximum 10 snapshots via rotation', async () => {
+  it('enforces maximum 10 tasks.db snapshots via rotation', async () => {
     const execMock = vi.fn();
     vi.doMock('../sqlite.js', () => ({ getNativeDb: () => ({ exec: execMock }) }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => null }));
     const tempDir = join(tmpdir(), `cleo-test-rot-${Date.now()}`);
     const backupDir = join(tempDir, 'backups', 'sqlite');
     mkdirSync(backupDir, { recursive: true });
@@ -63,13 +79,64 @@ describe('sqlite-backup', () => {
     const { vacuumIntoBackup } = await import('../sqlite-backup.js');
     await vacuumIntoBackup({ force: true });
 
-    const remaining = readdirSync(backupDir).filter((f) => f.endsWith('.db'));
+    const remaining = readdirSync(backupDir).filter(
+      (f) => f.startsWith('tasks-') && f.endsWith('.db'),
+    );
     expect(remaining.length).toBeLessThanOrEqual(10);
   });
 
-  it('debounce skips second call within debounce window', async () => {
+  it('enforces rotation independently per prefix (tasks + brain)', async () => {
+    const tasksExec = vi.fn();
+    const brainExec = vi.fn();
+    vi.doMock('../sqlite.js', () => ({ getNativeDb: () => ({ exec: tasksExec }) }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => ({ exec: brainExec }) }));
+    const tempDir = join(tmpdir(), `cleo-test-rot-prefix-${Date.now()}`);
+    const backupDir = join(tempDir, 'backups', 'sqlite');
+    mkdirSync(backupDir, { recursive: true });
+    vi.doMock('../../paths.js', () => ({ getCleoDir: () => tempDir }));
+
+    // Seed 11 tasks.db and 11 brain.db stale snapshots.
+    for (let i = 0; i < 11; i++) {
+      const day = String(i + 1).padStart(2, '0');
+      writeFileSync(join(backupDir, `tasks-202601${day}-120000.db`), 'fake');
+      writeFileSync(join(backupDir, `brain-202601${day}-120000.db`), 'fake');
+    }
+
+    const { vacuumIntoBackupAll } = await import('../sqlite-backup.js');
+    await vacuumIntoBackupAll({ force: true });
+
+    const files = readdirSync(backupDir);
+    const tasksFiles = files.filter((f) => f.startsWith('tasks-') && f.endsWith('.db'));
+    const brainFiles = files.filter((f) => f.startsWith('brain-') && f.endsWith('.db'));
+    expect(tasksFiles.length).toBeLessThanOrEqual(10);
+    expect(brainFiles.length).toBeLessThanOrEqual(10);
+  });
+
+  it('vacuumIntoBackupAll snapshots both tasks.db and brain.db', async () => {
+    const tasksExec = vi.fn();
+    const brainExec = vi.fn();
+    vi.doMock('../sqlite.js', () => ({ getNativeDb: () => ({ exec: tasksExec }) }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => ({ exec: brainExec }) }));
+    const tempDir = join(tmpdir(), `cleo-test-both-${Date.now()}`);
+    vi.doMock('../../paths.js', () => ({ getCleoDir: () => tempDir }));
+
+    const { vacuumIntoBackupAll } = await import('../sqlite-backup.js');
+    await vacuumIntoBackupAll({ force: true });
+
+    // Each DB should have received a wal_checkpoint and a VACUUM INTO call.
+    const assertExec = (mock: ReturnType<typeof vi.fn>) => {
+      const calls = mock.mock.calls.map((c) => c[0] as string);
+      expect(calls.some((c) => c.includes('wal_checkpoint'))).toBe(true);
+      expect(calls.some((c) => c.includes('VACUUM INTO'))).toBe(true);
+    };
+    assertExec(tasksExec);
+    assertExec(brainExec);
+  });
+
+  it('debounce skips second call within debounce window (tasks prefix)', async () => {
     const execMock = vi.fn();
     vi.doMock('../sqlite.js', () => ({ getNativeDb: () => ({ exec: execMock }) }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => null }));
     const tempDir = join(tmpdir(), `cleo-test-debounce-${Date.now()}`);
     vi.doMock('../../paths.js', () => ({ getCleoDir: () => tempDir }));
 
@@ -78,8 +145,49 @@ describe('sqlite-backup', () => {
     await vacuumIntoBackup({ force: true });
     const callCountAfterFirst = execMock.mock.calls.length;
 
-    // Second call without force -- should be debounced
+    // Second call without force — should be debounced
     await vacuumIntoBackup({ force: false });
     expect(execMock.mock.calls.length).toBe(callCountAfterFirst);
   });
+
+  it('listSqliteBackups and listBrainBackups return prefix-specific entries newest-first', async () => {
+    vi.doMock('../sqlite.js', () => ({ getNativeDb: () => null }));
+    vi.doMock('../brain-sqlite.js', () => ({ getBrainNativeDb: () => null }));
+    const tempDir = join(tmpdir(), `cleo-test-list-${Date.now()}`);
+    const backupDir = join(tempDir, 'backups', 'sqlite');
+    mkdirSync(backupDir, { recursive: true });
+    vi.doMock('../../paths.js', () => ({ getCleoDir: () => tempDir }));
+
+    // Write files then explicitly set mtimes so the listing sort (by mtime
+    // descending) is deterministic regardless of filesystem timestamp
+    // resolution. Without utimesSync, two files written in the same tight
+    // loop can share the same mtime and fall back to insertion order.
+    const f1 = join(backupDir, 'tasks-20260101-120000.db');
+    const f2 = join(backupDir, 'tasks-20260102-120000.db');
+    const f3 = join(backupDir, 'brain-20260103-120000.db');
+    writeFileSync(f1, 'fake');
+    writeFileSync(f2, 'fake');
+    writeFileSync(f3, 'fake');
+    // Use distinct epoch seconds, increasing with the date in the filename
+    // so that tasks-20260102 is strictly newer than tasks-20260101.
+    utimesSync(f1, 1_700_000_100, 1_700_000_100);
+    utimesSync(f2, 1_700_000_200, 1_700_000_200);
+    utimesSync(f3, 1_700_000_300, 1_700_000_300);
+
+    const { listSqliteBackups, listBrainBackups, listSqliteBackupsAll } = await import(
+      '../sqlite-backup.js'
+    );
+    const tasksList = listSqliteBackups();
+    const brainList = listBrainBackups();
+    const all = listSqliteBackupsAll();
+
+    expect(tasksList.map((e) => e.name)).toEqual([
+      'tasks-20260102-120000.db',
+      'tasks-20260101-120000.db',
+    ]);
+    expect(brainList.map((e) => e.name)).toEqual(['brain-20260103-120000.db']);
+    expect(Object.keys(all).sort()).toEqual(['brain', 'tasks']);
+    expect(all['tasks']?.length).toBe(2);
+    expect(all['brain']?.length).toBe(1);
+  });
 });

package/src/store/cleanup-legacy.ts

@@ -0,0 +1,208 @@
+/**
+ * Idempotent cleanup of legacy and stray CLEO database files.
+ *
+ * Provides two independent cleanup functions:
+ *
+ * 1. {@link detectAndRemoveLegacyGlobalFiles} — removes stale files left at
+ *    the global CLEO home directory (`getCleoHome()`) by pre-v2026.4.11
+ *    naming migrations. Safe to call on repeat invocations — existence-checks
+ *    guard every deletion.
+ *
+ *    Files targeted (see ADR-036 §Decision/Global-Tier table):
+ *      - workspace.db              (pre-nexus naming relic)
+ *      - workspace.db.bak-pre-rename  (safety copy from a long-landed rename)
+ *      - workspace.db-shm          (SQLite shared-memory sidecar of workspace.db)
+ *      - workspace.db-shm-wal      (SQLite WAL sidecar of workspace.db)
+ *      - nexus-pre-cleo.db.bak     (pre-CLEO backup of nexus — migration complete)
+ *
+ *    Live files (nexus.db, signaldock.db, machine-key, config.json, etc.) are
+ *    NEVER touched. The function only acts on the explicit LEGACY_FILES list.
+ *
+ * 2. {@link detectAndRemoveStrayProjectNexus} — removes a stray
+ *    `{projectRoot}/.cleo/nexus.db` that violates ADR-036's global-only
+ *    nexus contract. Some pre-v2026.4.11 code path accidentally created a
+ *    zero-byte nexus.db at project tier; this cleans it up on first run.
+ *
+ * @task T304
+ * @task T307
+ * @epic T299
+ * @adr ADR-036
+ * @why v2026.4.10 left workspace.db and pre-cleo backups at global tier;
+ *   ADR-036 mandates their deletion to eliminate diagnostic confusion and
+ *   false impressions of active legacy databases.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLogger } from '../logger.js';
+import { getCleoHome } from '../paths.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Exhaustive list of legacy filenames that MUST be removed from the global
+ * CLEO home directory. No other files are touched.
+ *
+ * @task T304
+ */
+const LEGACY_FILES: readonly string[] = [
+  'workspace.db',
+  'workspace.db.bak-pre-rename',
+  'workspace.db-shm',
+  'workspace.db-shm-wal',
+  'nexus-pre-cleo.db.bak',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result returned by {@link detectAndRemoveLegacyGlobalFiles}. */
+export interface LegacyCleanupResult {
+  /** Filenames (basename only) that were successfully deleted. */
+  removed: string[];
+  /** Files that could not be deleted, with error messages. */
+  errors: Array<{ file: string; error: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect and remove legacy global-tier files from the CLEO home directory.
+ *
+ * Idempotent: safe to call when some or all files are already absent. Each
+ * file is individually existence-checked before attempting deletion. Failures
+ * on individual files are captured in `errors` rather than thrown, so the
+ * caller receives a complete picture of what was (and was not) cleaned up.
+ *
+ * Logs each successful deletion at `info` level and each failure at `warn`
+ * level via the shared pino logger.
+ *
+ * @param cleoHomeOverride - Optional directory override for tests. When
+ *   omitted the canonical `getCleoHome()` path is used. Prefer passing this
+ *   parameter in test harnesses rather than mutating `CLEO_HOME` environment
+ *   variables, as it avoids global state contamination between test runs.
+ * @returns A {@link LegacyCleanupResult} describing what was removed and any
+ *   errors encountered.
+ *
+ * @example
+ * ```typescript
+ * // Production usage (runs against real global home)
+ * const result = detectAndRemoveLegacyGlobalFiles();
+ * if (result.removed.length > 0) {
+ *   // Legacy files were cleaned up
+ * }
+ *
+ * // Test usage (runs against tmp directory)
+ * const result = detectAndRemoveLegacyGlobalFiles('/tmp/fake-cleo-home');
+ * ```
+ *
+ * @task T304
+ * @epic T299
+ */
+export function detectAndRemoveLegacyGlobalFiles(cleoHomeOverride?: string): LegacyCleanupResult {
+  const log = getLogger('cleanup-legacy');
+  const cleoHome = cleoHomeOverride ?? getCleoHome();
+  const removed: string[] = [];
+  const errors: Array<{ file: string; error: string }> = [];
+
+  for (const fileName of LEGACY_FILES) {
+    const fullPath = path.join(cleoHome, fileName);
+    try {
+      if (fs.existsSync(fullPath)) {
+        fs.unlinkSync(fullPath);
+        removed.push(fileName);
+        log.info({ file: fullPath }, 'Removed legacy global file');
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ file: fileName, error: message });
+      log.warn({ file: fullPath, error: message }, 'Failed to remove legacy global file');
+    }
+  }
+
+  return { removed, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Project-tier stray nexus.db cleanup (T307)
+// ---------------------------------------------------------------------------
+
+/** Result returned by {@link detectAndRemoveStrayProjectNexus}. */
+export interface StrayNexusCleanupResult {
+  /** Whether a stray nexus.db was found and deleted. */
+  removed: boolean;
+  /** Absolute path that was checked (and removed if `removed` is true). */
+  path: string;
+}
+
+/**
+ * Detect and remove a stray project-tier `.cleo/nexus.db` file.
+ *
+ * ADR-036 declares nexus.db as **global-only** — it lives exclusively under
+ * `getCleoHome()` (e.g. `~/.local/share/cleo/nexus.db` on Linux). A
+ * zero-byte stray was discovered at `/mnt/projects/cleocode/.cleo/nexus.db`
+ * (created 2026-03-31), likely produced by an early `cleo init` / `cleo
+ * nexus init` invocation that ran before the canonical path was fully wired
+ * through `getNexusDbPath()`.
+ *
+ * This function is idempotent: calling it when no stray file exists is a
+ * no-op. It is designed to be called once per CLI startup (alongside
+ * {@link detectAndRemoveLegacyGlobalFiles}) so that users who upgrade to
+ * v2026.4.11 have the stray silently cleaned up on the first `cleo` run.
+ *
+ * @param projectRoot - Absolute path to the project root directory. When
+ *   omitted the caller is responsible for supplying the current project
+ *   root from `getProjectRoot()`. An override parameter is accepted here to
+ *   keep tests hermetic (avoids reading live `process.cwd()` state).
+ * @returns A {@link StrayNexusCleanupResult} indicating whether a file was
+ *   removed and the absolute path that was checked.
+ *
+ * @example
+ * ```typescript
+ * // Production usage
+ * import { getProjectRoot } from '../paths.js';
+ * const result = detectAndRemoveStrayProjectNexus(getProjectRoot());
+ * if (result.removed) {
+ *   // Stray project-tier nexus.db has been cleaned up
+ * }
+ *
+ * // Test usage (hermetic)
+ * const result = detectAndRemoveStrayProjectNexus('/tmp/fake-project-root');
+ * ```
+ *
+ * @task T307
+ * @epic T299
+ * @adr ADR-036
+ * @why ADR-036 §Decision/Global-Tier: nexus.db is global-only. A stray
+ *   project-tier copy was created by pre-v2026.4.11 code and must be removed
+ *   to prevent diagnostic confusion and guard against future regressions.
+ */
+export function detectAndRemoveStrayProjectNexus(projectRoot: string): StrayNexusCleanupResult {
+  const log = getLogger('cleanup-legacy');
+  const strayPath = path.join(projectRoot, '.cleo', 'nexus.db');
+
+  if (fs.existsSync(strayPath)) {
+    try {
+      fs.unlinkSync(strayPath);
+      log.warn(
+        { path: strayPath },
+        'Removed stray project-tier nexus.db (violates ADR-036 global-only contract)',
+      );
+      return { removed: true, path: strayPath };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(
+        { path: strayPath, error: message },
+        'Failed to remove stray project-tier nexus.db — manual deletion may be required',
+      );
+      return { removed: false, path: strayPath };
+    }
+  }
+
+  return { removed: false, path: strayPath };
+}

package/src/store/index.ts

@@ -61,6 +61,13 @@ export {
   SafetyDataAccessor,
   wrapWithSafety,
 } from './safety-data-accessor.js';
+export {
+  listBrainBackups,
+  listSqliteBackups,
+  listSqliteBackupsAll,
+  vacuumIntoBackup,
+  vacuumIntoBackupAll,
+} from './sqlite-backup.js';
 
 /**
  * Get a StoreProvider instance for the given working directory.