@cleocode/core 2026.4.31 → 2026.4.35

package/dist/store/brain-sqlite.js

@@ -0,0 +1,257 @@
+/**
+ * SQLite store for brain.db via drizzle-orm/node-sqlite + node:sqlite (DatabaseSync).
+ *
+ * Separate database from tasks.db for cognitive infrastructure (decisions,
+ * patterns, learnings). Follows the same singleton + WAL + migration pattern
+ * as sqlite.ts.
+ *
+ * @epic T5149
+ * @task T5128
+ */
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { drizzle } from 'drizzle-orm/node-sqlite';
+import { getCleoDirAbsolute } from '../paths.js';
+import * as brainSchema from './brain-schema.js';
+import { createSafetyBackup, migrateWithRetry, reconcileJournal, tableExists, } from './migration-manager.js';
+import { openNativeDatabase } from './sqlite.js';
+const _require = createRequire(import.meta.url);
+/** Database file name within .cleo/ directory. */
+const DB_FILENAME = 'brain.db';
+/** Schema version for newly created brain databases. Single source of truth. */
+export const BRAIN_SCHEMA_VERSION = '1.0.0';
+/** Singleton state for lazy initialization. */
+let _db = null;
+let _nativeDb = null;
+let _dbPath = null;
+/** Guard against concurrent initialization (async migration). */
+let _initPromise = null;
+/** Whether sqlite-vec extension loaded successfully. */
+let _vecLoaded = false;
+/**
+ * Get the path to the brain.db SQLite database file.
+ */
+export function getBrainDbPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), DB_FILENAME);
+}
+/**
+ * Resolve the path to the drizzle-brain migrations folder.
+ * Works from both src/ (dev via tsx) and dist/ (compiled via esbuild bundle).
+ *
+ * - Source layout: __dirname = src/store/ → need ../../migrations/drizzle-brain
+ * - Bundled layout: __dirname = dist/     → need ../migrations/drizzle-brain
+ */
+export function resolveBrainMigrationsFolder() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const isBundled = __dirname.endsWith('/dist') || __dirname.endsWith('\\dist');
+    const pkgRoot = isBundled ? join(__dirname, '..') : join(__dirname, '..', '..');
+    return join(pkgRoot, 'migrations', 'drizzle-brain');
+}
+// tableExists — delegated to migration-manager.ts (T132)
+/**
+ * Run drizzle migrations to create/update brain.db tables.
+ *
+ * Delegates to shared migration-manager.ts for journal reconciliation,
+ * retry logic, and safety backups. See T132 for consolidation rationale.
+ *
+ * @task T5128
+ * @task T132 - Unified migration system
+ */
+function runBrainMigrations(nativeDb, db) {
+    const migrationsFolder = resolveBrainMigrationsFolder();
+    // Safety backup before any migration work
+    if (tableExists(nativeDb, 'brain_decisions') && _dbPath) {
+        createSafetyBackup(_dbPath);
+    }
+    // Bootstrap baseline + reconcile stale journal entries
+    reconcileJournal(nativeDb, migrationsFolder, 'brain_decisions', 'brain');
+    // Run pending migrations with SQLITE_BUSY retry.
+    // Pass nativeDb + existenceTable so migrateWithRetry can auto-reconcile any
+    // partial migration (Scenario 3) that slips through the proactive check above.
+    migrateWithRetry(db, migrationsFolder, nativeDb, 'brain_decisions', 'brain');
+}
+/**
+ * Load the sqlite-vec extension into a native DatabaseSync instance.
+ * Returns true if the extension loaded successfully, false otherwise.
+ *
+ * The extension enables vec0 virtual tables for vector similarity search.
+ * Requires the database to be opened with allowExtension: true.
+ *
+ * @task T5157
+ */
+function loadBrainVecExtension(nativeDb) {
+    try {
+        const sqliteVec = _require('sqlite-vec');
+        sqliteVec.load(nativeDb);
+        return true;
+    }
+    catch {
+        // sqlite-vec not available or failed to load — non-fatal
+        return false;
+    }
+}
+/**
+ * Create the vec0 virtual table for brain embeddings.
+ * Called after migrations complete and sqlite-vec extension is loaded.
+ *
+ * The vec0 table is not managed by Drizzle (virtual tables are not
+ * supported by drizzle-orm's SQLite schema). Created via raw SQL.
+ *
+ * @task T5157
+ */
+function initializeBrainVec(nativeDb) {
+    nativeDb
+        .prepare('CREATE VIRTUAL TABLE IF NOT EXISTS brain_embeddings USING vec0(id TEXT PRIMARY KEY, embedding FLOAT[384])')
+        .run();
+}
+/**
+ * Check whether the sqlite-vec extension is loaded for the current brain.db.
+ */
+export function isBrainVecLoaded() {
+    return _vecLoaded;
+}
+/**
+ * Initialize the default embedding provider when brain.embedding.enabled is true.
+ *
+ * Called asynchronously after getBrainDb() completes its synchronous setup.
+ * Uses dynamic import to avoid circular dependencies and keep the heavy
+ * @huggingface/transformers bundle out of the critical startup path.
+ *
+ * Best-effort: errors are swallowed by the caller so DB access is never blocked.
+ *
+ * @task T539
+ */
+async function initEmbeddingProvider(cwd) {
+    try {
+        const { loadConfig } = await import('../config.js');
+        const config = await loadConfig(cwd);
+        if (config.brain?.embedding?.enabled) {
+            const { initDefaultProvider } = await import('../memory/brain-embedding.js');
+            await initDefaultProvider();
+        }
+    }
+    catch {
+        // Config load or provider init failed — non-fatal, embedding stays unavailable
+    }
+}
+/**
+ * Initialize the brain.db SQLite database (lazy, singleton).
+ * Creates the database file and tables if they don't exist.
+ * Returns the drizzle ORM instance (async via sqlite-proxy).
+ *
+ * Uses a promise guard so concurrent callers wait for the same
+ * initialization to complete (migrations are async).
+ */
+export async function getBrainDb(cwd) {
+    const requestedPath = getBrainDbPath(cwd);
+    // If singleton exists but points to different path, reset it
+    if (_db && _dbPath !== requestedPath) {
+        resetBrainDbState();
+    }
+    if (_db)
+        return _db;
+    // If already initializing, wait for the in-flight init
+    if (_initPromise)
+        return _initPromise;
+    _initPromise = (async () => {
+        const dbPath = requestedPath;
+        _dbPath = dbPath;
+        // Ensure directory exists
+        mkdirSync(dirname(dbPath), { recursive: true });
+        // Open file-backed SQLite via node:sqlite with WAL mode.
+        // allowExtension: true enables sqlite-vec extension loading.
+        const nativeDb = openNativeDatabase(dbPath, { allowExtension: true });
+        _nativeDb = nativeDb;
+        // Load sqlite-vec extension for vector similarity search (T5157).
+        // Non-fatal if unavailable — vec0 tables simply won't be created.
+        _vecLoaded = loadBrainVecExtension(nativeDb);
+        // Create drizzle ORM wrapper via node-sqlite
+        const db = drizzle({ client: nativeDb, schema: brainSchema });
+        // Run drizzle migrations (creates/updates tables)
+        runBrainMigrations(nativeDb, db);
+        // Create vec0 virtual table for embeddings if extension is loaded (T5157).
+        // Must run after migrations so the schema is consistent.
+        if (_vecLoaded) {
+            initializeBrainVec(nativeDb);
+        }
+        // Seed schema version for new databases (no-op if already set)
+        nativeDb
+            .prepare(`INSERT OR IGNORE INTO brain_schema_meta (key, value) VALUES ('schemaVersion', '${BRAIN_SCHEMA_VERSION}')`)
+            .run();
+        // Set singleton only after migrations complete
+        _db = db;
+        // Wire the default embedding provider when vec is loaded and embedding is enabled.
+        // Best-effort, async, never blocks DB access. (T539)
+        if (_vecLoaded) {
+            setImmediate(() => {
+                initEmbeddingProvider(cwd).catch(() => {
+                    // Non-fatal — embedding will be unavailable until next startup
+                });
+            });
+        }
+        return db;
+    })();
+    try {
+        return await _initPromise;
+    }
+    finally {
+        _initPromise = null;
+    }
+}
+/**
+ * Close the brain.db database connection and release resources.
+ */
+export function closeBrainDb() {
+    if (_nativeDb) {
+        try {
+            if (_nativeDb.isOpen) {
+                _nativeDb.close();
+            }
+        }
+        catch {
+            // Ignore close errors
+        }
+        _nativeDb = null;
+    }
+    _db = null;
+    _dbPath = null;
+    _vecLoaded = false;
+}
+/**
+ * Reset brain.db singleton state without saving.
+ * Used during tests or when database file is recreated.
+ * Safe to call multiple times.
+ */
+export function resetBrainDbState() {
+    if (_nativeDb) {
+        try {
+            if (_nativeDb.isOpen) {
+                _nativeDb.close();
+            }
+        }
+        catch {
+            // Ignore close errors
+        }
+        _nativeDb = null;
+    }
+    _db = null;
+    _dbPath = null;
+    _initPromise = null;
+    _vecLoaded = false;
+}
+/**
+ * Get the underlying node:sqlite DatabaseSync instance for brain.db.
+ * Useful for direct PRAGMA calls or raw SQL operations.
+ * Returns null if the database hasn't been initialized.
+ */
+export function getBrainNativeDb() {
+    return _nativeDb;
+}
+/**
+ * Re-export brain schema for external use.
+ */
+export { brainSchema };
+//# sourceMappingURL=brain-sqlite.js.map

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

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

package/dist/store/cache.js

@@ -0,0 +1,168 @@
+/**
+ * Index caching for O(1) label/phase/hierarchy lookups.
+ * Ported from lib/data/cache.sh
+ *
+ * @epic T4454
+ * @task T4530
+ */
+/**
+ * In-memory cache for task indices with checksum-based staleness detection.
+ */
+export class TaskCache {
+    labelIndex = new Map();
+    phaseIndex = new Map();
+    parentIndex = new Map();
+    childrenIndex = new Map();
+    depthIndex = new Map();
+    checksum = '';
+    initialized = false;
+    /**
+     * Compute a checksum from task data for staleness detection.
+     */
+    computeChecksum(tasks) {
+        return tasks
+            .map((t) => `${t.id}:${t.status}:${t.parentId ?? ''}:${t.phase ?? ''}:${(t.labels ?? []).join(',')}`)
+            .sort()
+            .join('|');
+    }
+    /**
+     * Initialize or rebuild cache from tasks.
+     * Returns true if cache was rebuilt, false if already valid.
+     */
+    init(tasks) {
+        const newChecksum = this.computeChecksum(tasks);
+        if (this.initialized && newChecksum === this.checksum) {
+            return false;
+        }
+        this.buildLabelIndex(tasks);
+        this.buildPhaseIndex(tasks);
+        this.buildHierarchyIndex(tasks);
+        this.checksum = newChecksum;
+        this.initialized = true;
+        return true;
+    }
+    buildLabelIndex(tasks) {
+        this.labelIndex.clear();
+        for (const task of tasks) {
+            if (!task.labels?.length)
+                continue;
+            for (const label of task.labels) {
+                const existing = this.labelIndex.get(label) ?? [];
+                existing.push(task.id);
+                this.labelIndex.set(label, existing);
+            }
+        }
+    }
+    buildPhaseIndex(tasks) {
+        this.phaseIndex.clear();
+        for (const task of tasks) {
+            if (!task.phase)
+                continue;
+            const existing = this.phaseIndex.get(task.phase) ?? [];
+            existing.push(task.id);
+            this.phaseIndex.set(task.phase, existing);
+        }
+    }
+    buildHierarchyIndex(tasks) {
+        this.parentIndex.clear();
+        this.childrenIndex.clear();
+        this.depthIndex.clear();
+        const taskMap = new Map(tasks.map((t) => [t.id, t]));
+        for (const task of tasks) {
+            this.parentIndex.set(task.id, task.parentId ?? null);
+            if (task.parentId) {
+                const siblings = this.childrenIndex.get(task.parentId) ?? [];
+                siblings.push(task.id);
+                this.childrenIndex.set(task.parentId, siblings);
+            }
+        }
+        // Compute depths
+        for (const task of tasks) {
+            let depth = 0;
+            let current = task;
+            const visited = new Set();
+            while (current.parentId && !visited.has(current.parentId)) {
+                visited.add(current.parentId);
+                const parent = taskMap.get(current.parentId);
+                if (!parent)
+                    break;
+                depth++;
+                current = parent;
+            }
+            this.depthIndex.set(task.id, depth);
+        }
+    }
+    /** Get task IDs by label. */
+    getTasksByLabel(label) {
+        return this.labelIndex.get(label) ?? [];
+    }
+    /** Get task IDs by phase. */
+    getTasksByPhase(phase) {
+        return this.phaseIndex.get(phase) ?? [];
+    }
+    /** Get all labels. */
+    getAllLabels() {
+        return [...this.labelIndex.keys()];
+    }
+    /** Get all phases. */
+    getAllPhases() {
+        return [...this.phaseIndex.keys()];
+    }
+    /** Get label count for a specific label. */
+    getLabelCount(label) {
+        return this.getTasksByLabel(label).length;
+    }
+    /** Get parent ID for a task. */
+    getParent(taskId) {
+        return this.parentIndex.get(taskId) ?? null;
+    }
+    /** Get children IDs for a task. */
+    getChildren(taskId) {
+        return this.childrenIndex.get(taskId) ?? [];
+    }
+    /** Get depth for a task. */
+    getDepth(taskId) {
+        return this.depthIndex.get(taskId) ?? 0;
+    }
+    /** Get child count. */
+    getChildCount(taskId) {
+        return this.getChildren(taskId).length;
+    }
+    /** Get root tasks (no parent). */
+    getRootTasks() {
+        return [...this.parentIndex.entries()]
+            .filter(([, parent]) => parent === null)
+            .map(([id]) => id);
+    }
+    /** Get leaf tasks (no children). */
+    getLeafTasks() {
+        const parentSet = new Set(this.childrenIndex.keys());
+        return [...this.parentIndex.keys()].filter((id) => !parentSet.has(id) || this.getChildCount(id) === 0);
+    }
+    /** Force invalidation and rebuild. */
+    invalidate() {
+        this.labelIndex.clear();
+        this.phaseIndex.clear();
+        this.parentIndex.clear();
+        this.childrenIndex.clear();
+        this.depthIndex.clear();
+        this.checksum = '';
+        this.initialized = false;
+    }
+    /** Get cache statistics. */
+    getStats() {
+        let maxDepth = 0;
+        for (const d of this.depthIndex.values()) {
+            if (d > maxDepth)
+                maxDepth = d;
+        }
+        return {
+            initialized: this.initialized,
+            labelCount: this.labelIndex.size,
+            phaseCount: this.phaseIndex.size,
+            taskCount: this.parentIndex.size,
+            maxDepth,
+        };
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/store/cache.js.map

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

package/dist/store/chain-schema.js

@@ -0,0 +1,51 @@
+/**
+ * Drizzle ORM schema for WarpChain storage in tasks.db.
+ *
+ * Tables: warp_chains, warp_chain_instances
+ * Stores chain definitions and runtime instances bound to epics.
+ *
+ * @task T5403
+ */
+import { sql } from 'drizzle-orm';
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+/** Chain instance status values. */
+export const WARP_CHAIN_INSTANCE_STATUSES = [
+    'pending',
+    'active',
+    'completed',
+    'failed',
+    'cancelled',
+];
+// === WARP_CHAINS TABLE ===
+/** Stored WarpChain definitions (serialized as JSON). */
+export const warpChains = sqliteTable('warp_chains', {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    version: text('version').notNull(),
+    description: text('description'),
+    definition: text('definition').notNull(), // JSON-serialized WarpChain
+    validated: integer('validated', { mode: 'boolean' }).default(false),
+    createdAt: text('created_at').default(sql `(datetime('now'))`),
+    updatedAt: text('updated_at').default(sql `(datetime('now'))`),
+}, (table) => [index('idx_warp_chains_name').on(table.name)]);
+// === WARP_CHAIN_INSTANCES TABLE ===
+/** Runtime chain instances bound to epics. */
+export const warpChainInstances = sqliteTable('warp_chain_instances', {
+    id: text('id').primaryKey(),
+    chainId: text('chain_id')
+        .notNull()
+        .references(() => warpChains.id, { onDelete: 'cascade' }),
+    epicId: text('epic_id').notNull(),
+    variables: text('variables'), // JSON
+    stageToTask: text('stage_to_task'), // JSON
+    status: text('status').notNull().default('pending'),
+    currentStage: text('current_stage'),
+    gateResults: text('gate_results'), // JSON array of GateResult
+    createdAt: text('created_at').default(sql `(datetime('now'))`),
+    updatedAt: text('updated_at').default(sql `(datetime('now'))`),
+}, (table) => [
+    index('idx_warp_instances_chain').on(table.chainId),
+    index('idx_warp_instances_epic').on(table.epicId),
+    index('idx_warp_instances_status').on(table.status),
+]);
+//# sourceMappingURL=chain-schema.js.map

package/dist/store/chain-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-schema.js","sourceRoot":"","sources":["../../src/store/chain-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE5E,oCAAoC;AACpC,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,SAAS;IACT,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,WAAW;CACH,CAAC;AAEX,4BAA4B;AAE5B,yDAAyD;AACzD,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CACnC,aAAa,EACb;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE;IAC5B,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IAClC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC;IAChC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,EAAE,4BAA4B;IACtE,SAAS,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACnE,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;IAC7D,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;CAC9D,EACD,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAC1D,CAAC;AAEF,qCAAqC;AAErC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAC3C,sBAAsB,EACtB;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC;SACtB,OAAO,EAAE;SACT,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;IAC3D,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IACjC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,OAAO;IACrC,WAAW,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,OAAO;IAC3C,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;IACnD,YAAY,EAAE,IAAI,CAAC,eAAe,CAAC;IACnC,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC,EAAE,2BAA2B;IAC9D,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;IAC7D,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAA,mBAAmB,CAAC;CAC9D,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,KAAK,CAAC,0BAA0B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;IACnD,KAAK,CAAC,yBAAyB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;IACjD,KAAK,CAAC,2BAA2B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;CACpD,CACF,CAAC"}

package/dist/store/cleanup-legacy.js

@@ -0,0 +1,171 @@
+/**
+ * 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 = [
+    'workspace.db',
+    'workspace.db.bak-pre-rename',
+    'workspace.db-shm',
+    'workspace.db-shm-wal',
+    'nexus-pre-cleo.db.bak',
+];
+// ---------------------------------------------------------------------------
+// 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) {
+    const log = getLogger('cleanup-legacy');
+    const cleoHome = cleoHomeOverride ?? getCleoHome();
+    const removed = [];
+    const errors = [];
+    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 };
+}
+/**
+ * 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) {
+    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 };
+}
+//# sourceMappingURL=cleanup-legacy.js.map