@cleocode/core 2026.4.9 → 2026.4.11

package/dist/store/signaldock-sqlite.js

@@ -0,0 +1,400 @@
+/**
+ * SQLite store for signaldock.db — local agent messaging database.
+ *
+ * Creates and manages .cleo/signaldock.db using node:sqlite directly.
+ * Runs the consolidated Diesel migration SQL (from signaldock-storage crate)
+ * to bootstrap all 22 tables for local agent infrastructure.
+ *
+ * This is the Node.js bootstrap path. In production cloud, the Rust
+ * signaldock-storage crate manages this DB via Diesel ORM directly.
+ * Locally, we create the DB here so that cleo init scaffolds the full
+ * .cleo/ directory with all databases ready.
+ *
+ * @task T223
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { getCleoDirAbsolute } from '../paths.js';
+const _require = createRequire(import.meta.url);
+const { DatabaseSync: DatabaseSyncClass } = _require('node:sqlite');
+/** Database file name within .cleo/ directory. */
+const DB_FILENAME = 'signaldock.db';
+/** Schema version for signaldock databases. */
+export const SIGNALDOCK_SCHEMA_VERSION = '2026.3.76';
+/**
+ * Get the path to the signaldock.db SQLite database file.
+ */
+export function getSignaldockDbPath(cwd) {
+    const cleoDir = cwd ? join(cwd, '.cleo') : getCleoDirAbsolute();
+    return join(cleoDir, DB_FILENAME);
+}
+// ---------------------------------------------------------------------------
+// Embedded migration SQL — bundled so signaldock.db works in ANY project,
+// not just the monorepo where crates/signaldock-storage/ exists.
+// Source: crates/signaldock-storage/migrations/
+// ---------------------------------------------------------------------------
+/**
+ * Ordered migration entries. Each has a name (for tracking) and SQL.
+ * Add new migrations to the END of this array.
+ */
+const EMBEDDED_MIGRATIONS = [
+    {
+        name: '2026-03-28-000000_initial',
+        sql: `-- Consolidated initial migration for SignalDock storage (19 sqlx migrations merged).
+CREATE TABLE IF NOT EXISTS users (
+    id TEXT PRIMARY KEY, email TEXT NOT NULL UNIQUE, password_hash TEXT NOT NULL,
+    name TEXT, slug TEXT, default_agent_id TEXT, username TEXT, display_username TEXT,
+    email_verified INTEGER NOT NULL DEFAULT 0, image TEXT, role TEXT NOT NULL DEFAULT 'user',
+    banned INTEGER NOT NULL DEFAULT 0, ban_reason TEXT, ban_expires TEXT,
+    two_factor_enabled INTEGER NOT NULL DEFAULT 0, metadata TEXT,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_users_slug ON users(slug);
+
+CREATE TABLE IF NOT EXISTS organization (
+    id TEXT PRIMARY KEY NOT NULL, name TEXT NOT NULL, slug TEXT, logo TEXT, metadata TEXT,
+    owner_id TEXT, created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_organization_slug ON organization(slug);
+
+CREATE TABLE IF NOT EXISTS agents (
+    id TEXT PRIMARY KEY, agent_id TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+    description TEXT, class TEXT NOT NULL DEFAULT 'custom',
+    privacy_tier TEXT NOT NULL DEFAULT 'public', owner_id TEXT REFERENCES users(id),
+    endpoint TEXT, webhook_secret TEXT, capabilities TEXT NOT NULL DEFAULT '[]',
+    skills TEXT NOT NULL DEFAULT '[]', avatar TEXT, messages_sent INTEGER NOT NULL DEFAULT 0,
+    messages_received INTEGER NOT NULL DEFAULT 0, conversation_count INTEGER NOT NULL DEFAULT 0,
+    friend_count INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT 'online',
+    last_seen INTEGER, payment_config TEXT, api_key_hash TEXT,
+    organization_id TEXT REFERENCES organization(id) ON DELETE SET NULL,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS agents_agent_id_idx ON agents(agent_id);
+CREATE INDEX IF NOT EXISTS agents_owner_idx ON agents(owner_id);
+CREATE INDEX IF NOT EXISTS agents_class_idx ON agents(class);
+CREATE INDEX IF NOT EXISTS agents_privacy_idx ON agents(privacy_tier);
+CREATE INDEX IF NOT EXISTS agents_org_idx ON agents(organization_id);
+
+CREATE TABLE IF NOT EXISTS conversations (
+    id TEXT PRIMARY KEY, participants TEXT NOT NULL,
+    visibility TEXT NOT NULL DEFAULT 'private', message_count INTEGER NOT NULL DEFAULT 0,
+    last_message_at INTEGER, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+    id TEXT PRIMARY KEY, conversation_id TEXT NOT NULL REFERENCES conversations(id),
+    from_agent_id TEXT NOT NULL, to_agent_id TEXT NOT NULL, content TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'text', status TEXT NOT NULL DEFAULT 'pending',
+    attachments TEXT NOT NULL DEFAULT '[]', group_id TEXT, metadata TEXT DEFAULT '{}',
+    reply_to TEXT, created_at INTEGER NOT NULL, delivered_at INTEGER, read_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS messages_conversation_idx ON messages(conversation_id);
+CREATE INDEX IF NOT EXISTS messages_from_agent_idx ON messages(from_agent_id);
+CREATE INDEX IF NOT EXISTS messages_to_agent_idx ON messages(to_agent_id);
+CREATE INDEX IF NOT EXISTS messages_created_at_idx ON messages(created_at);
+CREATE INDEX IF NOT EXISTS idx_messages_group_id ON messages(group_id) WHERE group_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_messages_reply_to ON messages(reply_to) WHERE reply_to IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS claim_codes (
+    id TEXT PRIMARY KEY, agent_id TEXT NOT NULL REFERENCES agents(id),
+    code TEXT NOT NULL UNIQUE, expires_at INTEGER NOT NULL, used_at INTEGER,
+    used_by TEXT REFERENCES users(id), created_at INTEGER NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS claim_codes_code_idx ON claim_codes(code);
+CREATE INDEX IF NOT EXISTS claim_codes_agent_idx ON claim_codes(agent_id);
+
+CREATE TABLE IF NOT EXISTS connections (
+    id TEXT PRIMARY KEY, agent_a TEXT NOT NULL REFERENCES agents(id),
+    agent_b TEXT NOT NULL REFERENCES agents(id), status TEXT NOT NULL DEFAULT 'pending',
+    initiated_by TEXT NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS connections_agent_a_idx ON connections(agent_a);
+CREATE INDEX IF NOT EXISTS connections_agent_b_idx ON connections(agent_b);
+
+CREATE TABLE IF NOT EXISTS delivery_jobs (
+    id TEXT PRIMARY KEY, message_id TEXT NOT NULL, payload TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending', attempts INTEGER NOT NULL DEFAULT 0,
+    max_attempts INTEGER NOT NULL DEFAULT 6, next_attempt_at INTEGER NOT NULL,
+    last_error TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_delivery_jobs_status ON delivery_jobs(status, next_attempt_at);
+
+CREATE TABLE IF NOT EXISTS dead_letters (
+    id TEXT PRIMARY KEY, message_id TEXT NOT NULL, job_id TEXT NOT NULL,
+    reason TEXT NOT NULL, attempts INTEGER NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_dead_letters_message ON dead_letters(message_id);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(content, from_agent_id, content='messages', content_rowid='rowid');
+INSERT INTO messages_fts(messages_fts) VALUES('rebuild');
+CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
+    INSERT INTO messages_fts(rowid, content, from_agent_id) VALUES (new.rowid, new.content, new.from_agent_id);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_ad AFTER DELETE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content, from_agent_id) VALUES('delete', old.rowid, old.content, old.from_agent_id);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_au AFTER UPDATE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content, from_agent_id) VALUES('delete', old.rowid, old.content, old.from_agent_id);
+    INSERT INTO messages_fts(rowid, content, from_agent_id) VALUES (new.rowid, new.content, new.from_agent_id);
+END;
+
+CREATE TABLE IF NOT EXISTS message_pins (
+    id TEXT PRIMARY KEY, message_id TEXT NOT NULL, conversation_id TEXT NOT NULL,
+    pinned_by TEXT NOT NULL, note TEXT, created_at INTEGER NOT NULL, UNIQUE(message_id, pinned_by)
+);
+CREATE INDEX IF NOT EXISTS idx_pins_conversation ON message_pins(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_pins_agent ON message_pins(pinned_by);
+
+CREATE TABLE IF NOT EXISTS attachments (
+    slug TEXT PRIMARY KEY, conversation_id TEXT NOT NULL, from_agent_id TEXT NOT NULL,
+    content BLOB NOT NULL, original_size INTEGER NOT NULL, compressed_size INTEGER NOT NULL,
+    content_hash TEXT NOT NULL, format TEXT NOT NULL DEFAULT 'text', title TEXT,
+    tokens INTEGER NOT NULL DEFAULT 0, expires_at INTEGER NOT NULL DEFAULT 0,
+    storage_key TEXT, mode TEXT NOT NULL DEFAULT 'draft',
+    version_count INTEGER NOT NULL DEFAULT 1, current_version INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS attachments_conversation_idx ON attachments(conversation_id);
+CREATE INDEX IF NOT EXISTS attachments_agent_idx ON attachments(from_agent_id);
+
+CREATE TABLE IF NOT EXISTS capabilities (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+    description TEXT NOT NULL, category TEXT NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS skills (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
+    description TEXT NOT NULL, category TEXT NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS agent_capabilities (
+    agent_id TEXT NOT NULL REFERENCES agents(id), capability_id TEXT NOT NULL REFERENCES capabilities(id),
+    PRIMARY KEY (agent_id, capability_id)
+);
+CREATE TABLE IF NOT EXISTS agent_skills (
+    agent_id TEXT NOT NULL REFERENCES agents(id), skill_id TEXT NOT NULL REFERENCES skills(id),
+    PRIMARY KEY (agent_id, skill_id)
+);
+
+CREATE TABLE IF NOT EXISTS accounts (
+    id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    account_id TEXT NOT NULL, provider_id TEXT NOT NULL, access_token TEXT, refresh_token TEXT,
+    id_token TEXT, access_token_expires_at TEXT, refresh_token_expires_at TEXT, scope TEXT,
+    password TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_accounts_user_id ON accounts(user_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_accounts_provider ON accounts(provider_id, account_id);
+
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY NOT NULL, user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token TEXT NOT NULL UNIQUE, ip_address TEXT, user_agent TEXT, expires_at TEXT NOT NULL,
+    active_organization_id TEXT, impersonated_by TEXT, active INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_token ON sessions(token);
+CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON sessions(user_id);
+
+CREATE TABLE IF NOT EXISTS verifications (
+    id TEXT PRIMARY KEY NOT NULL, identifier TEXT NOT NULL, value TEXT NOT NULL,
+    expires_at TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_verifications_identifier ON verifications(identifier);
+
+CREATE TABLE IF NOT EXISTS org_agent_keys (
+    id TEXT PRIMARY KEY NOT NULL, organization_id TEXT NOT NULL REFERENCES organization(id) ON DELETE CASCADE,
+    agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+    created_by TEXT NOT NULL, created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS org_agent_keys_org_idx ON org_agent_keys(organization_id);
+CREATE INDEX IF NOT EXISTS org_agent_keys_agent_idx ON org_agent_keys(agent_id);
+
+CREATE TABLE IF NOT EXISTS attachment_versions (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    version_number INTEGER NOT NULL, author_agent_id TEXT NOT NULL,
+    change_type TEXT NOT NULL DEFAULT 'patch', patch_text TEXT, storage_key TEXT NOT NULL,
+    content_hash TEXT NOT NULL, original_size INTEGER NOT NULL, compressed_size INTEGER NOT NULL,
+    tokens INTEGER NOT NULL, change_summary TEXT, sections_modified TEXT NOT NULL DEFAULT '[]',
+    tokens_added INTEGER NOT NULL DEFAULT 0, tokens_removed INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL, UNIQUE(slug, version_number)
+);
+CREATE INDEX IF NOT EXISTS idx_attachment_versions_slug ON attachment_versions(slug);
+CREATE INDEX IF NOT EXISTS idx_attachment_versions_author ON attachment_versions(author_agent_id);
+
+CREATE TABLE IF NOT EXISTS attachment_approvals (
+    id TEXT PRIMARY KEY, slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    reviewer_agent_id TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'pending', comment TEXT,
+    version_reviewed INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
+    UNIQUE(slug, reviewer_agent_id)
+);
+CREATE INDEX IF NOT EXISTS idx_attachment_approvals_slug ON attachment_approvals(slug);
+
+CREATE TABLE IF NOT EXISTS attachment_contributors (
+    slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    agent_id TEXT NOT NULL, version_count INTEGER NOT NULL DEFAULT 0,
+    total_tokens_added INTEGER NOT NULL DEFAULT 0, total_tokens_removed INTEGER NOT NULL DEFAULT 0,
+    first_contribution_at INTEGER NOT NULL, last_contribution_at INTEGER NOT NULL,
+    PRIMARY KEY (slug, agent_id)
+);`,
+    },
+    {
+        name: '2026-03-30-000001_agent_connections',
+        sql: `-- Add transport_type to agents table for connection mode classification.
+ALTER TABLE agents ADD COLUMN transport_type TEXT NOT NULL DEFAULT 'http';
+CREATE INDEX idx_agents_transport_type ON agents(transport_type);
+
+CREATE TABLE agent_connections (
+    id TEXT PRIMARY KEY NOT NULL, agent_id TEXT NOT NULL,
+    transport_type TEXT NOT NULL DEFAULT 'http', connection_id TEXT,
+    connected_at BIGINT NOT NULL, last_heartbeat BIGINT NOT NULL,
+    connection_metadata TEXT, created_at BIGINT NOT NULL,
+    FOREIGN KEY (agent_id) REFERENCES agents(agent_id) ON DELETE CASCADE,
+    UNIQUE(agent_id, connection_id)
+);
+CREATE INDEX idx_agent_connections_agent ON agent_connections(agent_id);
+CREATE INDEX idx_agent_connections_transport ON agent_connections(transport_type);
+CREATE INDEX idx_agent_connections_heartbeat ON agent_connections(last_heartbeat);`,
+    },
+    {
+        name: '2026-03-31-000001_agent_credentials',
+        sql: `-- Move agent credentials into signaldock.db agents table (T234 clean-cut).
+ALTER TABLE agents ADD COLUMN api_key_encrypted TEXT;
+ALTER TABLE agents ADD COLUMN api_base_url TEXT NOT NULL DEFAULT 'https://api.signaldock.io';
+ALTER TABLE agents ADD COLUMN classification TEXT;
+ALTER TABLE agents ADD COLUMN transport_config TEXT NOT NULL DEFAULT '{}';
+ALTER TABLE agents ADD COLUMN is_active INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE agents ADD COLUMN last_used_at INTEGER;
+CREATE INDEX IF NOT EXISTS idx_agents_is_active ON agents(is_active);
+CREATE INDEX IF NOT EXISTS idx_agents_last_used ON agents(last_used_at);`,
+    },
+];
+/**
+ * Ensure signaldock.db exists and has the full schema applied.
+ *
+ * Idempotent — safe to call multiple times. Uses `CREATE TABLE IF NOT EXISTS`
+ * and `CREATE INDEX IF NOT EXISTS` throughout.
+ *
+ * @returns Object with action ('created' | 'exists') and the database path.
+ */
+export async function ensureSignaldockDb(cwd) {
+    const dbPath = getSignaldockDbPath(cwd);
+    const alreadyExists = existsSync(dbPath);
+    // Ensure parent directory exists
+    mkdirSync(dirname(dbPath), { recursive: true });
+    // Open or create the database
+    const db = new DatabaseSyncClass(dbPath);
+    try {
+        // Set pragmas for optimal performance
+        db.exec('PRAGMA journal_mode = WAL');
+        db.exec('PRAGMA busy_timeout = 5000');
+        db.exec('PRAGMA synchronous = NORMAL');
+        db.exec('PRAGMA foreign_keys = ON');
+        db.exec('PRAGMA cache_size = -64000'); // 64MB
+        // Check if schema already applied (agents table as sentinel)
+        const hasSchema = (() => {
+            try {
+                const result = db
+                    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='agents'")
+                    .get();
+                return !!result;
+            }
+            catch {
+                return false;
+            }
+        })();
+        // Ensure migration tracking tables exist
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS _signaldock_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+      )
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS _signaldock_migrations (
+        name TEXT PRIMARY KEY,
+        applied_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+      )
+    `);
+        // Apply embedded migrations (works in ANY project, not just monorepo)
+        for (const migration of EMBEDDED_MIGRATIONS) {
+            // Skip already-applied migrations
+            const applied = db
+                .prepare('SELECT name FROM _signaldock_migrations WHERE name = ?')
+                .get(migration.name);
+            if (applied)
+                continue;
+            db.exec('BEGIN TRANSACTION');
+            try {
+                db.exec(migration.sql);
+                db.prepare('INSERT INTO _signaldock_migrations (name) VALUES (?)').run(migration.name);
+                db.exec('COMMIT');
+            }
+            catch (err) {
+                db.exec('ROLLBACK');
+                throw err;
+            }
+        }
+        // Record schema version
+        db.exec(`
+      INSERT OR REPLACE INTO _signaldock_meta (key, value, updated_at)
+      VALUES ('schema_version', '${SIGNALDOCK_SCHEMA_VERSION}', strftime('%s', 'now'))
+    `);
+        return {
+            action: alreadyExists && hasSchema ? 'exists' : 'created',
+            path: dbPath,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Check signaldock.db health — table count, WAL mode, schema version.
+ *
+ * Used by `cleo doctor` to verify signaldock.db integrity.
+ *
+ * @returns Health report object or null if DB doesn't exist.
+ */
+export async function checkSignaldockDbHealth(cwd) {
+    const dbPath = getSignaldockDbPath(cwd);
+    if (!existsSync(dbPath)) {
+        return {
+            exists: false,
+            path: dbPath,
+            tableCount: 0,
+            walMode: false,
+            schemaVersion: null,
+            foreignKeysEnabled: false,
+        };
+    }
+    const db = new DatabaseSyncClass(dbPath);
+    try {
+        const tables = db
+            .prepare("SELECT COUNT(*) as count FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+            .get();
+        const journalMode = db.prepare('PRAGMA journal_mode').get();
+        const fkEnabled = db.prepare('PRAGMA foreign_keys').get();
+        let schemaVersion = null;
+        try {
+            const meta = db
+                .prepare("SELECT value FROM _signaldock_meta WHERE key = 'schema_version'")
+                .get();
+            schemaVersion = meta?.value ?? null;
+        }
+        catch {
+            // Meta table may not exist
+        }
+        return {
+            exists: true,
+            path: dbPath,
+            tableCount: tables.count,
+            walMode: journalMode.journal_mode === 'wal',
+            schemaVersion,
+            foreignKeysEnabled: fkEnabled.foreign_keys === 1,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=signaldock-sqlite.js.map

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

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

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"}